CreateCustomAgent

Updated at:
Copy as MD

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 methodRequired configuration
ACR imageartifact.port, and type=acr, instanceId, namespace, repo, and tag in artifact.container.
Custom imageartifact.port, artifact.container.type=custom, and a complete customImage. The clientToken query parameter is required.
Code packageartifact.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 methodConfiguration
Internettype=public. Do not specify VPC fields.
VPCtype=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:

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

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

create

*CustomAgent

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/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 :

    Internet.

  • vpc :

    VPC.

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 :

    API key authentication.

  • USER :

    User identity.

API_KEY

accessScope

string

No

The user access scope.

Valid values:

  • ALL :

    All scopes.

  • SPECIFIED :

    Specified scope.

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 :

    Alibaba Cloud Container Registry.

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:

  • INTERACTIVE: 1 vCPU and 2 GiB of memory.

  • STANDARD: 2 vCPUs and 4 GiB of memory.

  • HEAVY: 4 vCPUs and 8 GiB of memory.

Valid values:

  • HEAVY :

    Heavy-load: 4 vCPUs and 8 GiB of memory.

  • INTERACTIVE :

    Interactive: 1 vCPU and 2 GiB of memory.

  • STANDARD :

    Standard: 2 vCPUs and 4 GiB of memory.

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:

  • AFFINITY: Session affinity.

  • ISOLATED_HEADER_FIELD: Associates sessions by using the request header specified in headerName.

  • ISOLATED_COOKIE: Not recommended.

  • DISABLED: A compatibility option. The response returns AFFINITY.

Valid values:

  • DISABLED :

    Compatibility option, with the response returning session affinity.

  • AFFINITY :

    Session affinity.

  • ISOLATED_HEADER_FIELD :

    Request header-based session policy.

  • ISOLATED_COOKIE :

    Cookie session option (not recommended)

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:

  • openai-chat-completion :

    OpenAI Chat Completions compatible protocol.

  • agui :

    AG-UI protocol.

  • custom :

    Custom protocol.

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 :

    The request is accepted.

ACCEPTED

statusAtAcceptance

string

The cache status at the time of acceptance.

Valid values:

  • READY :

    The cache is ready.

  • FAILED :

    Cache preparation failed.

  • PENDING :

    The cache is being prepared.

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:

  • Creating :

    The agent is being created.

  • Failed :

    The agent failed.

  • Running :

    The agent is running.

  • Updating :

    The agent is being updated.

  • Deleted :

    The agent is deleted.

  • Deleting :

    The agent is being deleted.

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:

  • waiting_retry :

    The execution is waiting for a retry.

  • pending :

    The execution is pending.

  • processing :

    The execution is in progress.

  • failed :

    The execution failed.

  • superseded :

    The version is superseded by a subsequent version.

  • succeeded :

    The execution succeeded.

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 :

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

    Alibaba Cloud Container Registry.

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 :

    ZIP archive.

  • tar.gz :

    GZIP-compressed TAR archive.

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:

  • INTERACTIVE: 1 vCPU and 2 GiB of memory.

  • STANDARD: 2 vCPUs and 4 GiB of memory.

  • HEAVY: 4 vCPUs and 8 GiB of memory.

Valid values:

  • HEAVY :

    Heavy-load: 4 vCPUs and 8 GiB of memory.

  • INTERACTIVE :

    Interactive: 1 vCPU and 2 GiB of memory.

  • STANDARD :

    Standard: 2 vCPUs and 4 GiB of memory.

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:

  • DISABLED :

    Compatibility option, with the response returning session affinity.

  • AFFINITY :

    Session affinity.

  • ISOLATED_HEADER_FIELD :

    Request header-based session policy.

  • ISOLATED_COOKIE :

    Cookie session option (not recommended)

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:

  • agui: AG-UI protocol.

  • openai-chat-completion: OpenAI Chat Completions compatible protocol.

  • custom: Custom protocol.

Valid values:

  • openai-chat-completion :

    OpenAI Chat Completions compatible protocol.

  • agui :

    AG-UI protocol.

  • custom :

    Custom protocol.

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 :

    Internet.

  • vpc :

    VPC.

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:

  • acr :

    ACR image source.

  • custom :

    Custom image source.

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 :

    Internet.

  • vpc :

    VPC.

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:

  • CANCELLED :

    Canceled.

  • STARTING :

    Starting.

  • FAILED :

    Failed.

  • QUEUED :

    Queued.

  • SUCCEEDED :

    Succeeded.

  • HEALTH_CHECKING :

    Performing health check.

  • CHECKING :

    Checking.

  • COPYING :

    Transferring.

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.