CreateAgentVersion

Updated at:
Copy as MD

Saves an agent version.

Operation description

Saves the currently effective configuration of a specified managed or custom agent as an immutable fixed version, and archives the version template and artifacts. This operation only saves the version and does not deploy an instance. Other types of agents, such as external agents, do not support versions and return AgentVersionSubtypeUnsupported. The latest release of the agent must be effective, meaning latestSpecVersion is equal to effectiveSpecVersion. The system generates an incrementing version number, agentVersion, such as v1 and v2, for each agent. The version number is unique within the agent, and the sequence numbers of deleted versions are not reused. This version number is used to query and delete versions, and for server endpoint references. Each agent can retain up to 50 undeleted versions. If the limit is reached, AgentVersionQuotaExceeded is returned. You can continue to save versions after deleting unused ones. Duplicate submissions with the same versionName and release serial number return the existing version and are not subject to the limit. If the versionName is the same but the release serial number is different, AgentVersionAlreadyExists is returned.

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

create

*Agent

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/agent/{#agentId}

None None

Request syntax

POST /workspaces/{workspaceId}/agents/{agentId}/versions HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example

workspaceId

string

Yes

The ID of the AgentCore workspace where the agent resides.

ws-0123456789abcdef01234

agentId

string

Yes

The ID of the managed or custom agent.

agent-0123456789abcdef0123456789abcdef

Request parameters

Parameter

Type

Required

Description

Example

body

object

No

The request body for saving a version.

versionName

string

Yes

The custom display name. After leading and trailing whitespaces are removed, the name must be 1 to 128 characters in length. It can contain Chinese characters, uppercase and lowercase letters, spaces, and punctuation marks, but cannot contain control characters. The version name must be unique among undeleted versions under the same agent and is case-sensitive. It cannot be modified after being saved. The version number agentVersion is generated by the system and is not determined by this field.

Production stable version V1.0

description

string

No

The version description. It can be up to 1,024 characters in length and cannot be modified after being saved.

Stable version for production environment

clientToken

string

No

The idempotency token generated by the client. This is a reserved parameter, and the backend does not currently provide persistent idempotency guarantees.

c2d8a6f0-3b1e-4a7d-9f25-6e4b0c1a8d37

Response elements

Element

Type

Description

Example

object

requestId

string

The request ID, which is used to locate and troubleshoot the request.

5E8F3C2A-1B4D-4F6E-9A7C-0D2B8E6F4A1C

message

string

The response message. The value is success if the request is successful, or an error message if the request fails.

success

httpStatusCode

integer

The HTTP status code.

200

code

string

The business status code. The value is SUCCESS if the request is successful, or an error code if the request fails.

SUCCESS

success

boolean

Indicates whether the request is successful.

data

object

The details of the saved fixed agent version. If a duplicate submission matches an existing version, the existing version is returned.

workspaceId

string

The ID of the AgentCore workspace where the agent that owns the version resides.

ws-0123456789abcdef01234

agentId

string

The ID of the managed or custom agent to which the version belongs.

agent-0123456789abcdef0123456789abcdef

agentVersion

string

The version number generated by the system in incrementing order for the agent, such as v1 and v2. It is used to query and delete versions, and for server endpoint references.

v1

versionName

string

The display name specified by the user when saving the version. For versions saved earlier without a recorded name, the agentVersion is returned.

Production stable version V1.0

targetSpecVersion

integer

The effective release serial number of the agent when the version is saved, which corresponds to the effectiveSpecVersion at that time. This value does not change after the version is saved.

2

description

string

The version description provided when saving the version. It can be up to 1,024 characters in length. If no description is provided during saving, this value is empty.

Stable version for production environment

artifactStatus

string

Indicates only whether the version template and artifact archiving is complete, and does not represent the deployment or running status. A value of READY indicates complete, and INVALID indicates missing or inconsistent archiving.

Valid values:

  • READY
  • INVALID

READY

configuration

object

The structure for managed agents is consistent with the data structure of GetManagedAgent, and the structure for custom agents is consistent with the data structure of GetCustomAgent. The data masking rules are the same.

{"agentId":"agent-0123456789abcdef0123456789abcdef","workspaceId":"ws-0123456789abcdef01234","name":"customer-service","description":"Customer service agent","status":"Running","latestSpecVersion":2,"instruction":"You are a customer service assistant."}

any

The values of the agent configuration items when the version is saved. The keys are the data field names returned by GetManagedAgent or GetCustomAgent, such as name, instruction, and model. The value types depend on the fields and can be strings, numbers, Boolean values, objects, or arrays.

customer-service

createdBy

string

The UID of the Alibaba Cloud account of the caller who saved the version. If a RAM user makes the call, this is the UID of the Alibaba Cloud main account to which the RAM user belongs.

1234567890123456

createdAt

string

The time when the version was saved, in ISO 8601 UTC format.

2026-08-12T01:02:03Z

Examples

Success response

JSON format

{
  "requestId": "5E8F3C2A-1B4D-4F6E-9A7C-0D2B8E6F4A1C",
  "message": "success",
  "httpStatusCode": 200,
  "code": "SUCCESS",
  "success": false,
  "data": {
    "workspaceId": "ws-0123456789abcdef01234",
    "agentId": "agent-0123456789abcdef0123456789abcdef",
    "agentVersion": "v1",
    "versionName": "Production stable version V1.0",
    "targetSpecVersion": 2,
    "description": "Stable version for the production environment",
    "artifactStatus": "READY",
    "configuration": {
      "key": "customer-service"
    },
    "createdBy": "1234567890123456",
    "createdAt": "2026-08-12T01:02:03Z"
  }
}

Error codes

HTTP status code

Error code

Error message

Description

400 AgentVersionSubtypeUnsupported AgentVersions are not supported for this agent subtype.
404 AgentVersionTargetNotFound The effective SpecVersion of the agent does not exist.
409 AgentVersionTargetNotEffective The latest SpecVersion of the agent is not effective yet.
409 AgentVersionAlreadyExists The AgentVersion already exists for this agent.
409 AgentVersionQuotaExceeded The agent already has the maximum of 50 saved AgentVersions. Delete unused versions before saving a new one.
409 AgentVersionArtifactInvalid The published artifact of the effective SpecVersion is not ready for archiving or is inconsistent. Publish the agent again before saving a version.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.