CreateAgentVersion
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
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:CreateAgentVersion |
create |
*Agent
|
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 |
| 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.