UpdateExternalAgent
Updates the model source, instructions, tools, and skills of a managed agent, and processes the configuration asynchronously.
Operation description
Updates the model, instruction, tool, or skill configurations saved on the platform for a managed agent to adjust its capability configurations after integration.
Update rules
Provide at least one updatable field. Omitted top-level fields retain their original configurations. You can set description=null to clear the description. The tools and skills fields are replaced in their entirety upon submission. You must include the items that you want to retain. Pass [] to clear the corresponding explicit list.
Switch model sources
To switch to PLATFORM, provide modelSource=PLATFORM and a valid model configuration, including the model connection ID and model name.
To switch to RUNTIME, update the Settings to modelSource=RUNTIME and do not commit the platform model. The original platform model configuration is removed when the source is switched.
When a template is used, configurations that belong to the template, such as instructions, are read from the template. A successful update indicates that the request is accepted. Invoke GetExternalAgent to query the configuration version and external accessed state. The clientToken parameter does not provide idempotence guarantees at this time.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:UpdateExternalAgent |
update |
*ExternalAgent
|
None | None |
Request syntax
PATCH /workspaces/{workspaceId}/external-agents/{agentId} HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The workspace ID. |
ws-1 |
| agentId |
string |
Yes |
The managed agent ID. |
agent-1 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| body |
object |
No |
The request body. |
|
| name |
string |
No |
The name of the managed agent. |
my-external-agent |
| description |
string |
No |
The description of the managed agent. |
A code review agent that runs in the user environment |
| modelSource |
string |
No |
The source of the model configuration. PLATFORM indicates that the platform parses and delivers the model configuration. RUNTIME indicates that the external runtime manages the model itself, and the model parameter cannot be passed at the same time. Valid values: PLATFORM (platform model) and RUNTIME (runtime model). Valid values:
|
PLATFORM |
| model |
object |
No |
The model configuration. This parameter is available only when modelSource is set to PLATFORM. |
|
| modelConnectionId |
string |
Yes |
The model connection ID. |
mc-1 |
| modelName |
string |
Yes |
The upstream model name. |
qwen-max |
| quota |
object |
No |
The model token quota configuration. If you do not pass this parameter, no quota is configured. |
|
| enabled |
boolean |
No |
Specifies whether to enable the token quota. Default value: true. If you set this parameter to false, the quota is disabled and existing quota rules are deleted. |
true |
| limitType |
string |
No |
The quota limit type. This parameter is required and verified by the backend when the quota is enabled. Fixed value: token. Valid values:
|
token |
| usageLimit |
integer |
No |
The maximum number of tokens that can be consumed in a single period. This parameter is required and verified by the backend when the quota is enabled. The value must be greater than 0. |
1000000 |
| periodType |
string |
No |
The statistical period of the quota. This parameter is required and verified by the backend when the quota is enabled. Valid values: day (daily) and month (monthly). Valid values:
|
day |
| instruction |
string |
No |
The agent instruction, which is used to guide the behavior of the agent. |
You are a code review assistant |
| tools |
array<object> |
No |
The list of tool configurations. |
|
|
object |
No |
The list of tool configurations. |
||
| name |
string |
Yes |
The tool name. |
code-reviewer |
| type |
string |
Yes |
The tool type. Valid values: MCP (MCP tool). Valid values:
|
MCP |
| skills |
array<object> |
No |
The list of skill configurations. |
|
|
array<object> |
No |
The list of skill configurations. |
||
| name |
string |
Yes |
The skill name. |
code-analysis |
| version |
string |
No |
The skill version field for compatibility with legacy requests. For new requests, use sourceType and versionSelector. Do not submit this parameter in combination with sourceType. |
1.0.0 |
| sourceType |
string |
No |
The skill source type. Valid values: REFERENCE (references AI Registry) and STATIC (statically provided with the package). Valid values:
|
REFERENCE |
| versionSelector |
object |
No |
The skill reference version selector, which supports LABEL tags and VERSION specific versions. If omitted, LABEL/latest is used. Selectors are not provided for STATIC sources. |
|
| type |
string |
No |
The version selector type. Valid values: LABEL (by tag) and VERSION (by specific version). Valid values:
|
LABEL |
| value |
string |
No |
The selector value. When the type is LABEL, the value is the tag name, such as latest. When the type is VERSION, the value is the specific version number. |
latest |
| template |
object |
No |
The agent template configuration. |
|
| aiRegistry |
object |
No |
The AI Registry template configuration. |
|
| name |
string |
Yes |
The name of the template in AI Registry. |
code-review-template |
| version |
string |
Yes |
The version of the template in AI Registry. |
1.0.0 |
| environment |
object |
No |
The credential binding configuration. If you do not pass this parameter, the original binding is retained. If you pass an object, you must explicitly provide a non-null credentialReferences list, and the list is replaced in its entirety. If the list is empty or environment is null, the binding is cleared. Empty objects and objects that contain only common environment variables are invalid. |
|
| credentialReferences |
array<object> |
No |
The list of credential references. You must explicitly provide this list when passing the environment object, and it cannot be null. The list is replaced in its entirety. If you do not pass environment during an update, the original binding is retained. If you pass an empty list or set environment to null, the binding is cleared. Pass only the credential ID, not the actual key. |
|
|
object |
No |
|||
| credentialId |
string |
No |
The credential ID. This parameter is required when passing a credential reference item and is verified by the backend. |
cred-example |
| clientToken |
string |
No |
The reserved query parameter. The backend does not currently provide idempotence guarantees for deduplication or recovery of original acceptance results based on this identifier. |
client-token-1 |
For the specific meanings and valid values of the request parameters, see the metric description below.
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The successful response for updating a managed agent. |
||
| requestId |
string |
The request ID. |
1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| message |
string |
The request processing result message. |
success |
| httpStatusCode |
integer |
The HTTP status code. The value is 200 for a successful request. |
200 |
| code |
string |
The business status code. The value is SUCCESS for a successful request. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
|
| data |
object |
The details of the updated managed agent. |
|
| agentId |
string |
The managed agent ID. |
agent-1 |
| workspaceId |
string |
The workspace ID. |
ws-1 |
| regionId |
string |
The region ID. |
cn-hangzhou |
| name |
string |
The name of the managed agent. |
my-external-agent |
| description |
string |
The description of the managed agent. |
A code review agent that runs in the user environment |
| status |
string |
The status of the managed agent. Valid values: Creating, Running, Failed, Updating, Deleting, and Deleted. Valid values:
|
Running |
| latestSpecVersion |
integer |
The latest specification version number. |
1 |
| latestVersionStatus |
string |
The processing status of the latest specification version. Valid values: pending, processing, waiting_retry, succeeded, failed, and superseded. Valid values:
|
pending |
| createMode |
string |
The creation mode. |
CUSTOM |
| runtime |
string |
The runtime type reported by the managed agent. |
qwenpaw |
| deployType |
string |
The deployment type. |
SELF_HOSTED |
| createdAt |
string |
The creation time in RFC 3339 format. |
2026-01-01T00:00:00Z |
| updatedAt |
string |
The update time in RFC 3339 format. |
2026-01-01T00:00:00Z |
| modelSource |
string |
The source of the model configuration. PLATFORM indicates that the platform parses and delivers the model configuration. RUNTIME indicates that the external runtime manages the model itself, and the model parameter cannot be passed at the same time. Valid values: PLATFORM (platform model) and RUNTIME (runtime model). Valid values:
|
PLATFORM |
| model |
object |
The model configuration. This parameter is available only when modelSource is set to PLATFORM. |
|
| modelConnectionId |
string |
The model connection ID. |
mc-1 |
| modelName |
string |
The upstream model name. |
qwen-max |
| quota |
object |
The model token quota configuration and usage status for the current period. This field is empty if no quota is configured. |
|
| enabled |
boolean |
Indicates whether the quota is enabled. This field is not returned if no quota is configured. |
true |
| limitType |
string |
The quota limit type. Currently, only token is supported. Valid values:
|
token |
| usageLimit |
integer |
The maximum number of tokens allowed to be consumed in a single period. |
1000000 |
| periodType |
string |
The quota statistical period. A value of day indicates daily, and a value of month indicates monthly. Valid values:
|
day |
| ruleStatus |
string |
The gateway quota rule status. This field is read-only and returned by the backend. |
ACTIVE |
| usedAmount |
integer |
The number of tokens consumed in the current period. This field is read-only and returned by the backend. |
12345 |
| overLimit |
boolean |
Indicates whether the quota is exceeded in the current period. This field is read-only and returned by the backend. |
false |
| instruction |
string |
The agent instruction, which is used to guide the behavior of the agent. |
You are a code review assistant |
| tools |
array<object> |
The list of tool configurations. |
|
|
object |
The list of tool configurations. |
||
| name |
string |
The tool name. |
code-reviewer |
| type |
string |
The tool type. Valid values: MCP (MCP tool). Valid values:
|
MCP |
| skills |
array<object> |
The list of skill configurations. |
|
|
array<object> |
The list of skill configurations. |
||
| name |
string |
The skill name. |
code-analysis |
| version |
string |
The current target version for compatibility with legacy clients. New clients use resolvedVersion and determine the effective runtime version based on appliedVersion. |
1.0.0 |
| sourceType |
string |
The skill source type. Valid values: REFERENCE (references AI Registry) and STATIC (statically provided with the package). Valid values:
|
REFERENCE |
| versionSelector |
object |
The skill reference version selector, which supports LABEL tags and VERSION specific versions. If omitted, LABEL/latest is used. Selectors are not provided for STATIC sources. |
|
| type |
string |
The version selector type. Valid values: LABEL (by tag) and VERSION (by specific version). Valid values:
|
LABEL |
| value |
string |
The selector value. When the type is LABEL, the value is the tag name, such as latest. When the type is VERSION, the value is the specific version number. |
latest |
| fromTemplate |
boolean |
Indicates whether the skill is from a fixed template. This field is read-only, and template items cannot be removed. |
false |
| resolvedVersion |
string |
The current target version. This field is read-only. |
1.0.0 |
| appliedVersion |
string |
The effective version applied at runtime. This field is read-only. |
1.0.0 |
| configuredSkills |
array<object> |
The explicitly configured skills. |
|
|
array<object> |
|||
| name |
string |
The name of the skill in the Workspace AI Registry. |
web-search |
| version |
string |
The legacy compatibility field. For new requests, use sourceType and versionSelector. |
1.0.0 |
| sourceType |
string |
The skill source type. Valid values: REFERENCE (references AI Registry) and STATIC (statically provided with the package). Valid values:
|
REFERENCE |
| versionSelector |
object |
The skill reference version selector, which supports LABEL tags and VERSION specific versions. If omitted, LABEL/latest is used. Selectors are not provided for STATIC sources. |
|
| type |
string |
The version selector type. Valid values: LABEL (by tag) and VERSION (by specific version). Valid values:
|
LABEL |
| value |
string |
The selector value. When the type is LABEL, the value is the tag name, such as latest. When the type is VERSION, the value is the specific version number. |
latest |
| template |
object |
The agent template configuration. |
|
| aiRegistry |
object |
The AI Registry template configuration. |
|
| name |
string |
The name of the template in AI Registry. |
code-review-template |
| version |
string |
The version of the template in AI Registry. |
1.0.0 |
| externalAgentStatus |
object |
The runtime status information reported by the managed agent. |
|
| heartbeatStatus |
string |
The heartbeat status. ONLINE indicates that the most recent heartbeat did not exceed the configured timeout threshold. STALE indicates that the heartbeat has timed out. UNKNOWN indicates that the heartbeat is missing or the format is invalid. Valid values:
Valid values:
|
ONLINE |
| lastHeartbeat |
string |
The time of the most recent heartbeat from the managed agent, in RFC 3339 format. |
2026-01-01T00:00:00Z |
| lastActiveAt |
string |
The time when the managed agent was last active, in RFC 3339 format. |
2026-01-01T00:00:00Z |
| localIP |
string |
The local IP address reported by the managed agent. |
10.0.0.42 |
| runtime |
string |
The runtime type reported by the managed agent. |
qwenpaw |
| environment |
object |
The credential binding configuration. |
|
| credentialReferences |
array<object> |
The list of credential references. You must explicitly provide this list when passing the environment object, and it cannot be null. The list is replaced in its entirety. If you do not pass environment during an update, the original binding is retained. If you pass an empty list or set environment to null, the binding is cleared. Pass only the credential ID, not the actual key. |
|
|
object |
|||
| credentialId |
string |
The credential ID. This parameter is required when passing a credential reference item and is verified by the backend. |
cred-example |
For the meanings of the fields in a successful response, see the metric description of the response parameters below.
Examples
Success response
JSON format
{
"requestId": "1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": false,
"data": {
"agentId": "agent-1",
"workspaceId": "ws-1",
"regionId": "cn-hangzhou",
"name": "my-external-agent",
"description": "Code review agent running in the user environment",
"status": "Running",
"latestSpecVersion": 1,
"latestVersionStatus": "pending",
"createMode": "CUSTOM",
"runtime": "qwenpaw",
"deployType": "SELF_HOSTED",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"modelSource": "PLATFORM",
"model": {
"modelConnectionId": "mc-1",
"modelName": "qwen-max",
"quota": {
"enabled": true,
"limitType": "token",
"usageLimit": 1000000,
"periodType": "day",
"ruleStatus": "ACTIVE",
"usedAmount": 12345,
"overLimit": false
}
},
"instruction": "You are a code review assistant",
"tools": [
{
"name": "code-reviewer",
"type": "MCP"
}
],
"skills": [
{
"name": "code-analysis",
"version": "1.0.0",
"sourceType": "REFERENCE",
"versionSelector": {
"type": "LABEL",
"value": "latest"
},
"fromTemplate": false,
"resolvedVersion": "1.0.0",
"appliedVersion": "1.0.0"
}
],
"configuredSkills": [
{
"name": "web-search",
"version": "1.0.0",
"sourceType": "REFERENCE",
"versionSelector": {
"type": "LABEL",
"value": "latest"
}
}
],
"template": {
"aiRegistry": {
"name": "code-review-template",
"version": "1.0.0"
}
},
"externalAgentStatus": {
"heartbeatStatus": "ONLINE",
"lastHeartbeat": "2026-01-01T00:00:00Z",
"lastActiveAt": "2026-01-01T00:00:00Z",
"localIP": "10.0.0.42",
"runtime": "qwenpaw"
},
"environment": {
"credentialReferences": [
{
"credentialId": "cred-example"
}
]
}
}
}
Error codes
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.