CreateCustomAgent
Creates a custom code or image agent in a specified workspace. Supports code package, ACR image, and custom image deployments, and executes the deployment asynchronously.
Operation description
Deploys a user-provided code package or container image as an agent in a workspace. This corresponds to the "Custom Code / Image" creation method in the console.
Before you begin
Prepare a writable workspace and submit name, roleArn, artifact, and runtime. In runtime, specify both compute and sessionPolicy. roleArn is the RAM role used by the agent to access your cloud resources.
Select a deployment method
| Deployment method | Required configuration |
| ACR image | artifact.port, and type=acr, instanceId, namespace, repo, and tag in artifact.container. |
| Custom image | artifact.port, artifact.container.type=custom, and a complete customImage. The clientToken query parameter is required. |
| Code package | artifact.port, and sourceUri, languageRuntime, and entrypoint in artifact.code. |
artifact.code and artifact.container are mutually exclusive. The service listening port ranges from 1 to 65535. You can specify a startup command for a container image by using artifact.container.entrypoint. If omitted, the default startup method of the image is used.
Code package
ZIP and TAR.GZ formats are supported. The compressed package size ranges from 1 to 500,000,000 bytes. Dependencies must be included in the package. The platform does not install dependencies or perform online builds.
Invoke ListAgentCodeRuntimes to query the active languageRuntime values.
For local files, first invoke GetAgentCodePackageUploadUrl. Upload the file directly by using the upload method, URL, and request headers returned in the response, and then commit sourceUri.
sourceUri supports oss:// or HTTPS object URLs with standard OSS public domain names, including signed URLs. Private OSS objects must allow the workspace role to read them. You can invoke GetAgentCodePackageOssRamAuthorizeUrl to complete the authorization first.
Read permissions, object existence, and size are checked upon commit, and a fixed copy is saved. If the transfer failed, the agent configuration is not created. Archive integrity and decompression are checked when the instance starts.
entrypoint is the startup command executed in the /code folder, such as python main.py. The command does not automatically execute shell pipelines or expand environment variables. For complex startup logic, write the logic into a script within the package.
Sample request body for a code package (the runtime environment is subject to the query result):
{
"name": "code-agent",
"roleArn": "acs:ram::1234567890123456:role/AgentRuntimeRole",
"artifact": {
"port": 8000,
"code": {
"sourceUri": "oss://example-code-bucket/releases/agent.zip",
"languageRuntime": "python3.12",
"entrypoint": "python main.py"
}
},
"runtime": {
"compute": {
"computeClass": "STANDARD"
},
"sessionPolicy": {
"type": "AFFINITY"
}
}
}
Custom image
For customImage.image, specify the complete image address. Tags or digests are supported. Do not include the protocol or user information. Configure the image pull network separately in customImage.pullNetwork:
| Pull method | Configuration |
| Internet | type=public. Do not specify VPC fields. |
| VPC | type=vpc. Specify vpcId, vSwitchId, and securityGroupId. |
If repository authentication is required, specify both customImage.username and customImage.password. For anonymous access, omit both. The password is not returned in the response. The image pull network and the agent runtime network are configured separately.
useImageCache=true applies only to ACR images. For custom images and code packages, use false or omit this field.
Runtime configuration
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 for a session, in seconds. Valid values: 60 to 86400. |
If sessionPolicy.type=ISOLATED_HEADER_FIELD, you must provide a valid HTTP request header name in headerName. Do not specify this field for other policies.
If network is omitted, the default access policy on the agent side is used. Actual access is still subject to the workspace network restrictions. When submitting access items, specify the corresponding enabled value.
The total number of items in ossMounts and agenticFsMounts cannot exceed 10. The mount target mountPath uses an absolute path within the container, such as /data/train. It cannot conflict with platform reserved directories, and cannot be duplicated or form parent-child directory overrides.
File mounting allows the agent to access persistent data. When using AgenticFS, you can call GetWorkspaceAgenticFsMountRamAuthorizeUrl to authorize the access point first.
The path for an OSS mount must be a non-empty directory prefix within the bucket. The server for an AgenticFS mount is the AccessPoint domain name, without a protocol, port, or path. The path is an existing non-empty relative directory within the AccessPoint. You cannot mount the root directory of the AccessPoint. If readOnly is omitted, the default value is false.
Environment variable names must be non-empty and unique in the list. Values are strings and can be empty strings. When configuring healthCheck, you must specify port. Omitting the health check means no health check is configured. When configuring logging.sls, specify both non-empty project and logstore.
Query results and retries
A successful response indicates that the request has been accepted. Save the agentId and call GetCustomAgent. Check latestVersionStatus, latestExecutionError, status, and sandboxPhaseCounts to confirm the configuration processing and instance status.
You must provide the clientToken query parameter when submitting a custom image. It is optional for ACR image and code package submissions. The token length is 1 to 128 characters. Letters, digits, periods, underscores, colons, and hyphens are allowed. Reuse the original token to retry the same submission. The same parameters return the existing acceptance result. Use a new token for different submission content.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:CreateCustomAgent |
create |
*CustomAgent
|
None | None |
Request syntax
POST /workspaces/{workspaceId}/custom-agents HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The ID of the workspace to which the custom code or image agent belongs. |
ws-a1b2c3d4e5f6 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| body |
object |
No |
The JSON configuration of the custom code or image agent. You must specify name, artifact, roleArn, and runtime. |
|
| useImageCache |
boolean |
No |
Specifies whether to use the image cache. If omitted during creation, the default value is false. You can explicitly set it to true or false. The new contract rejects null and invalid types. Existing compatible endpoints handle this based on migration agreements. In the current phase, the custom source is normalized to false by the console. The frontend omits it, and explicit true is rejected. The platform copy is still retained. |
true |
| agenticFsMounts |
array<object> |
No |
The NAS storage mount configuration. Currently, only the AgenticFS type is supported. It is used to mount file directories from access points to agent runtime instances. This is a list of AgenticFS directory mounts. The total number of items in this list and ossMounts cannot exceed 10. If omitted or set to [] during creation, no mounts are configured. During an update, omitting the field retains the existing mounts, and [] clears the mounts. Null is not accepted. |
|
|
object |
No |
An AgenticFS AccessPoint directory mount configuration item. |
||
| server |
string |
No |
The AccessPoint domain name. This field is required for each mount item and validated by the backend. Use the DomainName from the NAS ListAccessPoints response. Do not include the protocol, port, or path. |
ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com |
| path |
string |
No |
The existing non-empty relative directory under the AccessPoint. This field is required for each mount item. Root directories, absolute paths, and parent directory traversals are not allowed. |
workspace/data |
| mountPath |
string |
No |
The absolute mount path within the container, such as /data/train. Mount targets cannot be duplicated or form parent-child directory overrides, and must avoid platform reserved directories. |
/mnt/agenticfs/data |
| readOnly |
boolean |
No |
Specifies whether the mount is read-only. true indicates read-only, and false indicates read and write. If omitted, the default value is false. |
false |
| name |
string |
Yes |
The name of the custom code or image agent. The length is 1 to 128 characters after leading and trailing spaces are removed. The name must be unique within the same workspace. |
my-custom-agent |
| description |
string |
No |
The description of the agent purpose. The maximum length is 1024 characters after leading and trailing spaces are removed. |
Custom agent that provides conversation services |
| customImage |
object |
No |
The source of the custom image. This field is required when artifact.container.type is custom. Omit this field for other sources. |
|
| image |
string |
No |
The image address. This field is required when submitting customImage and is validated by the backend. Specify the complete registry[:port]/repository:tag or registry[:port]/repository@sha256:digest. Multi-level paths are supported. Do not include the protocol or user information. |
registry.example.com/team/agent:v1 |
| skipTlsVerify |
boolean |
No |
Specifies whether to skip HTTPS certificate verification. |
false |
| pullNetwork |
object |
No |
The image pull network configuration. This field is required when submitting customImage and is validated by the backend. Specify the complete independent pull network configuration. For the Internet, only pass type=public. |
|
| type |
string |
No |
The pull network type. This field is required when submitting pullNetwork and is validated by the backend. The default value for new creations is public. It is independent of the agent runtime network. Valid values:
|
public |
| vpcId |
string |
No |
The VPC ID. This field is required when type is vpc. The associated account and region are validated by the backend. |
vpc-example |
| vSwitchId |
string |
No |
The vSwitch ID. This field is required when type is vpc. The vSwitch must belong to the selected VPC. |
vsw-example |
| securityGroupId |
string |
No |
The vSwitch ID. This field is required when type is vpc. The vSwitch must belong to the selected VPC. |
sg-example |
| username |
string |
No |
The username for the repository. |
reader |
| password |
string |
No |
The password or token for the repository. |
example-registry-token |
| accessMode |
string |
No |
The inbound access mode. Valid values:
|
API_KEY |
| accessScope |
string |
No |
The user access scope. Valid values:
|
ALL |
| artifact |
object |
Yes |
The artifact deployment configuration. You must specify the service listening port and choose either code or container as the deployment method. |
|
| port |
integer |
Yes |
The TCP port listened on by the agent service. Valid values: 1 to 65535. |
8080 |
| code |
object |
No |
The code package deployment configuration. This parameter is mutually exclusive with container. You must provide sourceUri, languageRuntime, and entrypoint, and specify artifact.port. ZIP and TAR.GZ formats are supported. Dependencies must be included in the package by the caller. |
|
| sourceUri |
string |
Yes |
The source URI of the code package. OSS URIs (oss://) and HTTPS object URLs of a standard OSS public domain name (including OSS signed URLs) are supported. External sites, custom domain names, and extra authentication request headers are not supported. For local uploads, use the sourceUri returned by GetAgentCodePackageUploadUrl. The URI is revalidated and transferred during creation or update. A fixed oss:// URI of the platform is returned after saving and can be reused for regular updates. |
oss://my-agent-bucket/packages/main.zip |
| languageRuntime |
string |
Yes |
The identifier of the code runtime environment, such as python3.12. When creating or switching environments, use the identifier returned by ListAgentCodeRuntimes. The identifier is validated by the current version catalog and is not a fixed enum. |
python3.12 |
| entrypoint |
string |
Yes |
The startup command for the code package. This parameter is required in code package mode. The working directory is the extracted code root directory /code, such as python main.py. Quotes and escapes are supported. Environment variables, pipes, and logical operations are not automatically expanded. Use scripts within the package for complex commands. |
python main.py |
| container |
object |
No |
The container image deployment configuration. This parameter is mutually exclusive with code. For ACR sources, specify type=acr, instanceId, namespace, repo, and tag. For custom sources, specify type=custom and provide the complete customImage. |
|
| type |
string |
Yes |
The image source type. acr indicates an ACR image, and custom indicates a custom image source. For the corresponding source configurations, refer to the descriptions of artifact.container and customImage. Valid values:
|
acr |
| namespace |
string |
No |
The namespace to which the ACR image repository belongs. This parameter cannot be empty. |
my-agent |
| repo |
string |
No |
The name of the image repository in the ACR namespace. This parameter cannot be empty. |
chat-agent |
| instanceId |
string |
No |
The ID of the ACR instance to which the image repository belongs. This parameter cannot be empty. |
cri-a1b2c3d4e5f6 |
| tag |
string |
No |
The image tag used for deployment. This parameter cannot be empty. When updating the tag, you must also provide artifact.port and other required image fields. |
v1.0.0 |
| entrypoint |
string |
No |
The optional image startup command. If specified, it must be a non-empty string. If omitted, the default startup method of the image is used. |
python app.py |
| roleArn |
string |
Yes |
The ARN of the RAM role used by the agent to access user cloud resources. The role must have permissions to access the cloud resources. |
acs:ram::1234567890123456:role/agentcore-runtime-role |
| 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 resource configuration for the agent runtime instance. |
|
| computeClass |
string |
Yes |
The compute specification. Valid values:
Valid values:
|
STANDARD |
| sessionPolicy |
object |
Yes |
The session policy configuration used to set the session association method for requests. |
|
| type |
string |
Yes |
The session policy type. Valid values:
Valid values:
|
AFFINITY |
| headerName |
string |
No |
The name of the request header for session identification. This parameter is required when type is set to ISOLATED_HEADER_FIELD and must be a valid HTTP request header name. Do not specify this parameter for other policies. |
X-Session-Id |
| hpa |
object |
No |
The 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 |
Yes |
Specifies whether to enable auto scaling. Default value: false. |
|
| minSandboxCount |
integer |
No |
The minimum number of instances. Valid values: 0 to 100. Default value: 1. This value cannot be greater than maxSandboxCount. |
1 |
| maxSandboxCount |
integer |
No |
The maximum number of instances. Valid values: 0 to 100. Default value: 10. This value cannot be less than minSandboxCount. |
10 |
| 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. |
600 |
| environment |
object |
No |
The environment variable configuration passed to the agent runtime process. |
|
| variables |
array<object> |
No |
The list of environment variables. Each item includes a name and a value. The entire list is replaced during an update. |
|
|
object |
No |
An environment variable configuration item. |
||
| name |
string |
Yes |
The name of the environment variable. This parameter cannot be empty and must be unique within the current environment variable list. |
LOG_LEVEL |
| value |
string |
Yes |
The value of the environment variable. This parameter must be a string. Empty strings are allowed. |
info |
| network |
object |
No |
The network access configuration for the agent. If this object is provided, omitted access items are treated as allowed. The actual accessible range is still restricted by the workspace network configuration. To retain the original restrictions during an update, specify both accessInternet and accessVpc. |
|
| accessInternet |
object |
No |
The Internet access configuration. If this access item is omitted, Internet access is not restricted on the agent side. However, the workspace must still allow Internet access. |
|
| enabled |
boolean |
No |
Specifies whether to allow the agent to access the Internet. A Boolean value must be provided when accessInternet is configured. For this setting to take effect, the workspace must also allow Internet access. |
|
| accessVpc |
object |
No |
The user VPC access configuration. If this access item is omitted, VPC access is not restricted on the agent side. However, the workspace must still be configured to allow access to the user VPC. |
|
| enabled |
boolean |
No |
Specifies whether to allow the agent to access the user VPC configured for the workspace. A Boolean value must be provided when accessVpc is configured. For this setting to take effect, the workspace must also allow VPC access. |
|
| logging |
object |
No |
The log delivery configuration for the agent. You can specify the Simple Log Service project and Logstore. After a successful creation or update, verify whether logs are delivered properly. |
|
| sls |
object |
No |
The Simple Log Service log delivery destination. When this object is configured, neither project nor logstore can be empty. |
|
| project |
string |
No |
The name of the Simple Log Service project that receives agent logs. |
my-agent-logs |
| logstore |
string |
No |
The name of the Simple Log Service Logstore that receives agent logs. |
agent-runtime |
| observability |
object |
No |
The high-code agent observability configuration. |
|
| enabled |
boolean |
No |
Specifies whether to enable agent observability. |
|
| healthCheck |
object |
No |
The optional HTTP health check configuration. If this object is provided, port must be specified. Unspecified items use default values. Omitting this object during creation means no health check is configured. During an update, omitting this top-level field retains the original configuration, while passing null removes the health check. |
|
| port |
integer |
No |
The port accessed for health checks. This parameter is required when health checks are configured. Valid values: 1 to 65535. |
8080 |
| path |
string |
No |
The HTTP health check path. It must start with a forward slash (/). Default value: /healthz. |
/healthz |
| intervalSeconds |
integer |
No |
The interval between two health checks, in seconds. This parameter must be a positive integer. Default value: 10. |
10 |
| timeoutSeconds |
integer |
No |
The timeout period for a single health check, in seconds. This parameter must be a positive integer and less than intervalSeconds. Default value: 2. |
2 |
healthyThreshold
deprecated
|
integer |
No |
This parameter does not take effect. Omit this parameter. |
1 |
| unhealthyThreshold |
integer |
No |
The number of consecutive health check failures required to mark the instance as unhealthy. This parameter must be a positive integer. Default value: 3. |
3 |
| ossMounts |
array<object> |
No |
The list of OSS directory mounts. You can specify a combined maximum of 10 items for OSS and agenticFsMounts. When you update this parameter, the entire list is replaced. Pass an empty array [] to clear the list. |
|
|
object |
No |
The configuration of an OSS directory mount. |
||
| bucketName |
string |
No |
The name of the OSS bucket. This parameter is required for each mount. The name must be 3 to 63 characters in length and can contain only lowercase letters, digits, and hyphens. It cannot start or end with a hyphen. |
my-agent-data |
| path |
string |
No |
The non-empty relative object directory prefix in the bucket. This parameter is required for each mount. Root directory and parent directory traversal are not allowed. |
datasets/train |
| mountPath |
string |
No |
The absolute mount path within the container, such as /data/train. Mount targets cannot be duplicated or form parent-child directory overrides, and must avoid platform reserved directories. |
/mnt/oss/train |
| readOnly |
boolean |
No |
Specifies whether the mount is read-only. true indicates read-only, and false indicates read and write. If omitted, the default value is false. |
|
| protocol |
array<object> |
No |
The list of invocation protocols supported by the agent. Each item includes the protocol type, and optional paths and request headers. When you update this parameter, the entire list is replaced. |
|
|
array<object> |
No |
The configuration of an invocation protocol, including its paths and request headers. |
||
| type |
string |
Yes |
The Protocol Type of the invoke protocol. Valid values: agui: AG-UI protocol. openai-chat-completion: OpenAI Chat Completions compatible protocol. custom: custom protocol. Valid values:
|
agui |
| paths |
array<object> |
No |
The list of API paths for the current protocol. |
|
|
object |
No |
An API path and its description. |
||
| name |
string |
Yes |
The non-empty API path for the current protocol. |
/agui |
| description |
string |
No |
The description of the current API path. |
AG-UI chat API |
| headers |
object |
No |
The request header configuration for the current protocol. The key is a non-empty request header name, and the value must be a string. |
|
|
string |
No |
The string value of the request header. |
application/json |
|
| clientToken |
string |
No |
The idempotency token passed as a query parameter. This parameter is required when you explicitly submit a customImage or set container.type to custom. It is optional when you submit an ACR image or a code package. The token must be 1 to 128 characters in length and can contain letters, digits, periods, underscores, colons, and hyphens. Reuse the same token for retries of the same submission. If you use the same token for different parameters, the request is rejected. |
custom-agent-request-20261010-001 |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| requestId |
string |
The unique identifier of the request, used to locate and troubleshoot issues. |
550E8400-E29B-41D4-A716-446655440000 |
| message |
string |
The message that describes the processing result of the request. The value is success if the request succeeds. |
success |
| httpStatusCode |
integer |
The HTTP status code of the request. The value is 200 if the request succeeds. |
200 |
| code |
string |
The result code of the request. The value is SUCCESS if the request succeeds. |
SUCCESS |
| success |
boolean |
Indicates whether the request was processed successfully. A value of true indicates that the request was processed successfully. However, a successful creation, update, or deletion does not mean that the backend operation is complete. |
|
| data |
object |
The latest submitted configuration and status of the custom code or image agent. A successful response indicates that the request is accepted, but the configuration may not have taken effect. |
|
| imageCachePreparation |
object |
The summary of the acceptance for the current image cache preparation. |
|
| imageId |
string |
The ID of the cache associated with this request. |
img-example |
| submissionStatus |
string |
The acceptance status of the cache preparation. Valid values:
|
ACCEPTED |
| statusAtAcceptance |
string |
The cache status at the time of acceptance. Valid values:
|
PENDING |
| useImageCache |
boolean |
Specifies whether the image cache is enabled. |
true |
| imageCacheId |
string |
The ID of the currently associated image cache. |
img-example |
| agenticFsMounts |
array<object> |
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. This represents the latest submitted NAS mounts. |
|
|
object |
An AgenticFS AccessPoint directory mount configuration item. |
||
| server |
string |
The AgenticFS access point domain name used for mounting. |
ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com |
| path |
string |
The relative directory within the mounted access point. |
workspace/data |
| mountPath |
string |
The absolute mount path within the container, such as /data/train. Mount targets cannot be duplicated or form parent-child directory overrides, and must avoid platform reserved directories. |
/mnt/agenticfs/data |
| readOnly |
boolean |
Specifies whether the mount is read-only. A value of true indicates a read-only mount, and a value of false indicates a read/write mount. |
false |
| agentId |
string |
The unique identifier of the custom code or image agent. You can obtain this ID from the response of CreateCustomAgent or ListCustomAgents. |
agent-550e8400e29b41d4a716446655440000 |
| workspaceId |
string |
The ID of the workspace to which the custom code or image agent belongs. |
ws-a1b2c3d4e5f6 |
| name |
string |
The name of the custom code or image agent. |
my-custom-agent |
| description |
string |
The description of the agent. |
Custom agent that provides conversation services |
| status |
string |
The overall status of the agent. Valid values: Creating, Running, Failed, Updating, Deleting, and Deleted. To check the execution progress of the latest configuration, query latestVersionStatus. Valid values:
|
Running |
| latestSpecVersion |
integer |
The latest configuration version number. Updates with the same configuration may retain the original version number. This field does not indicate that the configuration has taken effect. |
1 |
| effectiveSpecVersion |
integer |
The effective configuration version. |
1 |
| latestVersionStatus |
string |
The execution status corresponding to latestSpecVersion. Valid values: pending, processing, waiting_retry, succeeded, failed, and superseded. Valid values:
|
succeeded |
| latestExecutionError |
object |
The waiting or execution error of the latest configuration version. This field is returned only when the version is waiting for a retry or fails to execute. |
|
| code |
string |
The reason code for the waiting or execution failure of the latest configuration, which is used to determine the subsequent processing method. The value is ACRDependencyNotReady when waiting for ACR configuration. Specific failures retain publicly available stable reason codes. |
AgentExecutionFailed |
| message |
string |
The description of the reason why the latest configuration is waiting or has failed to execute. Refer to code and retryable to determine what to do next. |
The agent execution failed. Check the configuration and resubmit |
| retryable |
boolean |
Specifies whether automatic retries are performed. A value of true indicates that you can query again later. A value of false indicates that you must check and fix the configuration based on the reason before resubmitting. |
|
| createMode |
string |
The creation method of the agent. The value is CUSTOM for custom code or image agents. |
CUSTOM |
| deployType |
string |
The deployment method of the agent. Custom code or image agents are deployed and managed by the platform, and the value is MANAGED. |
MANAGED |
| accessMode |
string |
The inbound access mode. Valid values:
|
API_KEY |
| accessScope |
string |
The user access scope. Valid values:
|
ALL |
| createdAt |
string |
The time when the agent was created. The time is in ISO 8601 format. A trailing Z indicates the UTC time zone. Fractional seconds may be included. |
2026-10-10T06:00:00Z |
| updatedAt |
string |
The time when the agent was last updated. The time is in ISO 8601 format. A trailing Z indicates the UTC time zone. Fractional seconds may be included. |
2026-10-10T06:05:00Z |
| regionId |
string |
The region ID of the workspace to which the agent belongs. |
cn-hangzhou |
| sandboxPhaseCounts |
object |
The count of instances by runtime phase. Valid keys include PENDING (creating or initializing), RUNNING (running), HIBERNATING (hibernating), HIBERNATED (hibernated), RESUMING (resuming), TERMINATING (terminating), and FAILED (failed). Only phases that actually occur are returned. Missing keys are treated as 0. |
|
|
integer |
The number of instances in the corresponding running phase. |
1 |
|
| roleArn |
string |
The ARN of the RAM role used by the agent to access user cloud resources. |
acs:ram::1234567890123456:role/agentcore-runtime-role |
| artifact |
object |
The latest submitted deployment artifact configuration, including the service listening port and ACR container image. To check whether it has taken effect, refer to latestVersionStatus. |
|
| port |
integer |
The TCP port listened on by the agent service. |
8080 |
| code |
object |
The code package deployment configuration, which is mutually exclusive with container. The code package uses the ZIP or TAR.GZ format. Dependencies are packaged by the user, and the platform does not install dependencies or build online. |
|
| sourceUri |
string |
The fixed oss:// address of the code package referenced by the currently saved configuration, excluding the signature parameters of the source HTTPS link. This can be used to reuse an existing code package. To download the content, call GetAgentCodePackageDownloadUrl. |
oss://agentcore-platform-example/code-packages/workspaces/ws-a1b2c3d4e5f6/550e8400-e29b-41d4-a716-446655440000/package.zip |
| languageRuntime |
string |
The code runtime environment identifier of the currently saved configuration. The runtime image uses a saved snapshot. Adding a new version to the directory does not automatically change the existing configuration. |
python3.12 |
| entrypoint |
string |
The startup command for the code package. This parameter is required in code package mode. The working directory is the extracted code root directory /code, such as python main.py. Quotes and escapes are supported. Environment variables, pipes, and logical operations are not automatically expanded. Use scripts within the package for complex commands. |
python main.py |
| container |
object |
The latest submitted ACR container image configuration. |
|
| type |
string |
The image source type. acr indicates an ACR image, and custom indicates a custom image source. For the corresponding source configurations, refer to the descriptions of artifact.container and customImage. Valid values:
|
acr |
| namespace |
string |
The namespace to which the ACR image repository belongs. |
my-agent |
| repo |
string |
The name of the image repository in the ACR namespace. |
chat-agent |
| instanceId |
string |
The ID of the ACR instance to which the image repository belongs. |
cri-a1b2c3d4e5f6 |
| tag |
string |
The latest submitted image tag. |
v1.0.0 |
| entrypoint |
string |
The custom executable program and startup parameters. If not configured, the default startup method of the image is used. |
python app.py |
| codePackageInfo |
object |
The currently saved code package information. |
|
| fileName |
string |
The original code package file name. |
main.zip |
| fileSize |
integer |
The compressed size of the code package. |
123 |
| format |
string |
The code package format. Valid values:
|
zip |
| etag |
string |
The ETag of the code package object. |
fixed-etag |
| crc64 |
string |
The CRC64 of the code package object. |
456 |
| runtime |
object |
The latest committed runtime configuration, including compute specifications, session policy, and elastic policy. |
|
| compute |
object |
The compute resource configuration for the agent runtime instance. |
|
| computeClass |
string |
The compute specification. Valid values:
Valid values:
|
STANDARD |
| sessionPolicy |
object |
The session policy configuration of the agent. |
|
| type |
string |
The session policy type. AFFINITY: session affinity. ISOLATED_HEADER_FIELD: uses the request header specified by headerName to associate sessions. ISOLATED_COOKIE is not recommended. The compatible value DISABLED in the request is returned as AFFINITY. Valid values:
|
AFFINITY |
| headerName |
string |
The name of the HTTP request header used by the session policy, applicable to ISOLATED_HEADER_FIELD. |
X-Session-Id |
| hpa |
object |
The elastic policy configuration of the agent. |
|
| enabled |
boolean |
Specifies whether elastic 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. |
10 |
| maxConcurrentSessionsPerSandbox |
integer |
The maximum number of concurrent sessions per instance in the current configuration. |
20 |
| sessionTtlSeconds |
integer |
The maximum idle time of a session in the current configuration, in seconds. |
600 |
| environment |
object |
The environment variable configuration of the agent process. |
|
| variables |
array<object> |
The latest submitted list of environment variables. |
|
|
object |
An environment variable configuration item. |
||
| name |
string |
The name of the environment variable. |
LOG_LEVEL |
| value |
string |
The string value of the environment variable. Empty strings are allowed. |
info |
| network |
object |
The network access configuration of the agent. The actual access scope is also limited by the workspace network configuration. |
|
| accessInternet |
object |
The Internet access configuration of the agent. If this item is not configured, access is allowed on the agent side, but it is still limited by the workspace. |
|
| enabled |
boolean |
Specifies whether Internet access is allowed on the agent side. The actual access is still limited by the workspace. |
|
| accessVpc |
object |
The user VPC access configuration of the agent. If this item is not configured, access is allowed on the agent side, but it is still limited by the workspace. |
|
| enabled |
boolean |
Specifies whether access to the user VPC configured in the workspace is allowed on the agent side. The actual access is still limited by the workspace. |
|
| logging |
object |
The latest submitted log delivery configuration. |
|
| sls |
object |
The SLS log delivery destination. |
|
| project |
string |
The name of the Simple Log Service project that receives agent logs. |
my-agent-logs |
| logstore |
string |
The name of the Simple Log Service Logstore that receives agent logs. |
agent-runtime |
| observability |
object |
The high-code agent observability configuration. |
|
| enabled |
boolean |
Specifies whether to enable agent observability. |
|
| healthCheck |
object |
The HTTP health check configuration of the agent. Empty if not configured. |
|
| port |
integer |
The port accessed for HTTP health checks. |
8080 |
| path |
string |
The HTTP health check path. |
/healthz |
| intervalSeconds |
integer |
The interval between two health checks, in seconds. |
10 |
| timeoutSeconds |
integer |
The timeout period for a single health check, in seconds. |
2 |
healthyThreshold
deprecated
|
integer |
This parameter does not take effect. |
1 |
| unhealthyThreshold |
integer |
The number of consecutive health check failures required to mark the agent as unhealthy. |
3 |
| protocol |
array<object> |
The list of invocation protocol configurations for the agent. |
|
|
array<object> |
The configuration of an invocation protocol, including its paths and request headers. |
||
| type |
string |
The invoke protocol type. Valid values:
Valid values:
|
agui |
| paths |
array<object> |
The list of API paths for the current protocol. |
|
|
object |
An API path and its description. |
||
| name |
string |
The API path corresponding to the current protocol. |
/agui |
| description |
string |
The description of the current API path. |
AG-UI chat API |
| headers |
object |
The request header configuration for the current protocol. The key is the header name and the value is a string. |
|
|
string |
The string value of the request header. |
application/json |
|
| ossMounts |
array<object> |
The list of recently submitted OSS directory mounts. |
|
|
object |
The configuration of an OSS directory mount. |
||
| bucketName |
string |
The name of the mounted OSS bucket. |
my-agent-data |
| path |
string |
The non-empty relative directory prefix in the currently configured bucket. |
datasets/train |
| mountPath |
string |
The absolute mount path within the container, such as /data/train. Mount targets cannot be duplicated or form parent-child directory overrides, and must avoid platform reserved directories. |
/mnt/oss/train |
| readOnly |
boolean |
Specifies whether the mount is read-only. A value of true indicates a read-only mount, and a value of false indicates a read/write mount. |
|
| customImage |
object |
The recently saved source and the verified username for the source. The source may be in preparation or failed. The password is not returned. |
|
| image |
string |
The recently saved source address, which may still be in preparation. |
registry.example.com/team/agent:v1 |
| skipTlsVerify |
boolean |
The saved HTTPS certificate exception option. |
false |
| pullNetwork |
object |
The saved dedicated pull network. |
|
| type |
string |
The pull network type. This field is required when submitting pullNetwork and is validated by the backend. The default value for new creations is public. It is independent of the agent runtime network. Valid values:
|
public |
| vpcId |
string |
The VPC ID. This field is required when type is vpc. The associated account and region are validated by the backend. |
vpc-example |
| vSwitchId |
string |
The vSwitch ID. This field is required when type is vpc. The vSwitch must belong to the selected VPC. |
vsw-example |
| securityGroupId |
string |
The vSwitch ID. This field is required when type is vpc. The vSwitch must belong to the selected VPC. |
sg-example |
| username |
string |
The verified username for the source. |
reader |
| currentImage |
object |
The image source snapshot of the current active configuration version. This value is null before the initial configuration takes effect and does not represent the health status. |
|
| sourceType |
string |
The image source type of the current active version. Valid values:
|
custom |
| image |
string |
The original image address of the custom source. |
registry.example.com/team/agent:v1 |
| username |
string |
The source username of the active image. |
reader |
| skipTlsVerify |
boolean |
The certificate exception option of the custom source. |
false |
| pullNetwork |
object |
The dedicated pull network of the custom source. |
|
| type |
string |
The pull network type. This field is required when submitting pullNetwork and is validated by the backend. The default value for new creations is public. It is independent of the agent runtime network. Valid values:
|
public |
| vpcId |
string |
The VPC ID. This field is required when type is vpc. The associated account and region are validated by the backend. |
vpc-example |
| vSwitchId |
string |
The vSwitch ID. This field is required when type is vpc. The vSwitch must belong to the selected VPC. |
vsw-example |
| securityGroupId |
string |
The vSwitch ID. This field is required when type is vpc. The vSwitch must belong to the selected VPC. |
sg-example |
| instanceId |
string |
The instance ID of the ACR source. |
cri-example |
| namespace |
string |
The namespace of the ACR source. |
team |
| repo |
string |
The repository name of the ACR source. |
agent |
| tag |
string |
The tag of the ACR source. |
v1 |
| imagePreparation |
object |
The currently associated image preparation task. The phase indicates the acceptance status. Query the preparation API for real-time progress. A standard save operation does not create an image preparation task. |
|
| preparationId |
string |
The task ID submitted from the console for this operation, which is not the RM operation ID. |
agent-example:1 |
| phase |
string |
The phase of the current image preparation. Configuration acceptance does not indicate successful deployment. Valid values:
|
QUEUED |
Examples
Success response
JSON format
{
"requestId": "550E8400-E29B-41D4-A716-446655440000",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": false,
"data": {
"imageCachePreparation": {
"imageId": "img-example",
"submissionStatus": "ACCEPTED",
"statusAtAcceptance": "PENDING"
},
"useImageCache": true,
"imageCacheId": "img-example",
"agenticFsMounts": [
{
"server": "ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com",
"path": "workspace/data",
"mountPath": "/mnt/agenticfs/data",
"readOnly": false
}
],
"agentId": "agent-550e8400e29b41d4a716446655440000",
"workspaceId": "ws-a1b2c3d4e5f6",
"name": "my-custom-agent",
"description": "Custom agent that provides conversation services",
"status": "Running",
"latestSpecVersion": 1,
"effectiveSpecVersion": 1,
"latestVersionStatus": "succeeded",
"latestExecutionError": {
"code": "AgentExecutionFailed",
"message": "Agent execution failed. Check the configuration and resubmit",
"retryable": false
},
"createMode": "CUSTOM",
"deployType": "MANAGED",
"accessMode": "API_KEY",
"accessScope": "ALL",
"createdAt": "2026-10-10T06:00:00Z",
"updatedAt": "2026-10-10T06:05:00Z",
"regionId": "cn-hangzhou",
"sandboxPhaseCounts": {
"key": 1
},
"roleArn": "acs:ram::1234567890123456:role/agentcore-runtime-role",
"artifact": {
"port": 8080,
"code": {
"sourceUri": "oss://agentcore-platform-example/code-packages/workspaces/ws-a1b2c3d4e5f6/550e8400-e29b-41d4-a716-446655440000/package.zip",
"languageRuntime": "python3.12",
"entrypoint": "python main.py"
},
"container": {
"type": "acr",
"namespace": "my-agent",
"repo": "chat-agent",
"instanceId": "cri-a1b2c3d4e5f6",
"tag": "v1.0.0",
"entrypoint": "python app.py"
}
},
"codePackageInfo": {
"fileName": "main.zip",
"fileSize": 123,
"format": "zip",
"etag": "fixed-etag",
"crc64": "456"
},
"runtime": {
"compute": {
"computeClass": "STANDARD"
},
"sessionPolicy": {
"type": "AFFINITY",
"headerName": "X-Session-Id"
},
"hpa": {
"enabled": false,
"minSandboxCount": 1,
"maxSandboxCount": 10,
"maxConcurrentSessionsPerSandbox": 20,
"sessionTtlSeconds": 600
}
},
"environment": {
"variables": [
{
"name": "LOG_LEVEL",
"value": "info"
}
]
},
"network": {
"accessInternet": {
"enabled": false
},
"accessVpc": {
"enabled": false
}
},
"logging": {
"sls": {
"project": "my-agent-logs",
"logstore": "agent-runtime"
}
},
"observability": {
"enabled": false
},
"healthCheck": {
"port": 8080,
"path": "/healthz",
"intervalSeconds": 10,
"timeoutSeconds": 2,
"healthyThreshold": 1,
"unhealthyThreshold": 3
},
"protocol": [
{
"type": "agui",
"paths": [
{
"name": "/agui",
"description": "AG-UI conversation API"
}
],
"headers": {
"key": "application/json"
}
}
],
"ossMounts": [
{
"bucketName": "my-agent-data",
"path": "datasets/train",
"mountPath": "/mnt/oss/train",
"readOnly": false
}
],
"customImage": {
"image": "registry.example.com/team/agent:v1",
"skipTlsVerify": false,
"pullNetwork": {
"type": "public",
"vpcId": "vpc-example",
"vSwitchId": "vsw-example",
"securityGroupId": "sg-example"
},
"username": "reader"
},
"currentImage": {
"sourceType": "custom",
"image": "registry.example.com/team/agent:v1",
"username": "reader",
"skipTlsVerify": false,
"pullNetwork": {
"type": "public",
"vpcId": "vpc-example",
"vSwitchId": "vsw-example",
"securityGroupId": "sg-example"
},
"instanceId": "cri-example",
"namespace": "team",
"repo": "agent",
"tag": "v1"
},
"imagePreparation": {
"preparationId": "agent-example:1",
"phase": "QUEUED"
}
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | AgentCodePackage.Invalid | The code package source or format is invalid. | |
| 400 | AgentCodePackage.SizeExceeded | The compressed code package exceeds 500000000 bytes. | |
| 400 | AcrEditionUnsupported | The ACR edition is not supported. | |
| 400 | AcrAccountUnsupported | The ACR account is not supported. | |
| 400 | AcrRegionUnsupported | The ACR region is not supported. | |
| 400 | InvalidParameter.%s | The specified parameter %s is not valid. Reason: %s Expected format: %s | |
| 400 | InvalidArgument | The specified request parameter is invalid. | |
| 400 | CustomImage.InvalidReference | Use registry/repository:tag or registry/repository@sha256:digest without a scheme or credentials. | |
| 400 | CustomImage.CredentialPairRequired | Provide non-empty customImage.username and customImage.password together, or omit both for anonymous access. | |
| 403 | AgentCodePackage.SourceAccessDenied | The workspace role cannot read the source code package object. | |
| 403 | AcrRamUnauthorized | The shared role is not authorized for the specified ACR instance. | |
| 403 | AgenticFsRamUnauthorized | Authorize the Workspace role for this AgenticFS AccessPoint. | |
| 403 | AgenticFsMountDisabled | New or changed AgenticFS mounts are not enabled. | |
| 502 | AgentCodePackage.CopyFailed | The code package could not be transferred to platform storage. The configuration was not saved. | |
| 404 | AgentCodePackage.SourceNotFound | The source code package object does not exist. | |
| 404 | AgenticFsAccessPointNotFound | The AccessPoint is not available in this Workspace account and region. | |
| 503 | AgentCodePackage.StorageUnavailable | The platform code package storage is unavailable. | |
| 503 | AgentCodePackage.AuthorizationUnavailable | The code package authorization service is unavailable. | |
| 503 | AgentCodeRuntime.Unavailable | The code runtime catalog is unavailable or invalid. | |
| 503 | AcrAuthorizationServiceUnavailable | The authorization service is temporarily unavailable. | |
| 503 | AgenticFsIntegrationNotConfigured | The NAS discovery and RAM authorization integration is not configured. | |
| 503 | AgenticFsServiceUnavailable | NAS resource or RAM authorization lookup failed. | |
| 503 | ImageCacheUnavailable | No image cache execution resources are available in the requested cache region. | |
| 503 | ACRProviderUnavailable | The Agent image credential provider is temporarily unavailable. | |
| 504 | AgentCodePackage.CopyTimeout | The code package transfer timed out. The configuration was not saved. | |
| 409 | AgentCodePackage.SourceChanged | The source object changed during reading. Retry this operation. | |
| 409 | AgentCodePackage.Unavailable | The saved configuration has no downloadable code package. | |
| 409 | AcrRoleConflict | The workspace has conflicting authorization role references. | |
| 409 | AcrPrerequisiteNotReady | The workspace is not ready for private image access. | |
| 409 | AcrCapacityUnsupported | The workspace capacity mode is not supported. | |
| 409 | WorkspaceDeleting | The workspace is being deleted. | |
| 409 | AcrOperationConflict | A conflicting authorization operation is in progress. | |
| 409 | AgenticFsPrerequisiteNotReady | AgenticFS requires an active RAM-enabled AccessPoint and user VPC access. | |
| 409 | ImageCacheRegionMismatch | The registered cache region is incompatible with the requested region. | |
| 409 | WorkspaceNotReady | The Agent workspace is not ready. | |
| 409 | ImageCacheVersionConflict | The source tag is already registered with another digest. Select a new tag. | |
| 409 | ImageCacheDeleting | The image cache is being deleted. | |
| 409 | ImageCacheTargetChanged | The current execution configuration is incompatible with the registered cache target. | |
| 409 | ImageCacheNetworkUnavailable | No configured source transfer network supports the requested access modes. | |
| 409 | SubmissionPending | The submission result is not confirmed. Query the current Agent and cache status before submitting again. | |
| 409 | ACRCapabilityUnsupported | The Agent execution target does not support the required image credentials. | |
| 409 | ACRProfileConflict | The Agent image credential configuration conflicts with the current profile. | |
| 409 | Agent.Binding.NotReady | The %s binding for workspace %s is not ready. | |
| 409 | Agent.Operation.Conflict | The Agent operation conflicts with its current state. | |
| 409 | ImageCacheBusy | Another image cache or Agent submission is in progress; retry later. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.