CreateExternalAgent
Creates an agent that runs in an external environment, saves the configurations for the platform model, instructions, tools, and skills, and asynchronously processes the onboarding configuration.
Operation description
Registers an agent hosted in a user runtime environment, which corresponds to the "Managed Agent" in the console. After registration, you can continue to obtain onboarding information and complete the connection.
Configure a managed agent
Provide name and select the configuration based on the model source:
modelSource | Model configuration |
PLATFORM | Uses a platform model. Provide model.modelConnectionId and model.modelName. |
RUNTIME | The model is managed by an external runtime environment. Do not submit model. |
If modelSource is omitted but model is provided, it is processed as PLATFORM. If both are omitted, the agent cannot be created.
Configure instructions, MCP tools, and skills by using instruction, tools, and skills. You can also reference an agent template by using template.aiRegistry. The external process is deployed by the caller. This operation does not create a platform runtime instance.
Onboarding sequence
Step 1: After creation, save the agentId and call GetExternalAgent to query the configuration processing result.
Step 2: After the latest configuration takes effect, call GetExternalAgentBootstrapOptions to obtain the available onboarding networks.
Step 3: Select an available network and call CreateExternalAgentBootstrapToken to obtain the onboarding token and CMS configuration. The external process completes the onboarding.
clientToken is a reserved query parameter and does not provide idempotency guarantees at this time.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:CreateExternalAgent |
create |
*ExternalAgent
|
None | None |
Request syntax
POST /workspaces/{workspaceId}/external-agents HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The workspace ID. |
ws-1 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| body |
object |
No |
The request body. |
|
| name |
string |
Yes |
The name of the managed agent. |
my-external-agent |
| description |
string |
No |
The description of the managed agent. |
Code review agent running 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. Available only when modelSource is 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 not passed, no quota is configured. |
|
| enabled |
boolean |
No |
Specifies whether to enable the token quota. Defaults to true if not specified. Passing false disables and deletes existing quota rules. |
true |
| limitType |
string |
No |
The quota limit type. Required and validated by the backend when the quota is enabled. Fixed value: token. Valid values:
|
token |
| usageLimit |
integer |
No |
The maximum number of tokens allowed to be consumed in a single period. Required and validated by the backend when the quota is enabled, and must be greater than 0. |
1000000 |
| periodType |
string |
No |
The quota statistical period. Required and validated by the backend when the quota is enabled. Valid values: day (daily) and month (monthly). Valid values:
|
day |
| instruction |
string |
No |
The agent instruction, 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. Use sourceType and versionSelector for new requests. Do not submit it in combination with sourceType. |
1.0.0 |
| sourceType |
string |
No |
The skill source type. REFERENCE references the AI Registry. STATIC is statically provided with the deployment package. Valid values:
|
REFERENCE |
| versionSelector |
object |
No |
The skill reference version selector. Supports LABEL tags and VERSION specific versions. Defaults to LABEL/latest if omitted. Selectors are not provided for STATIC sources. |
|
| type |
string |
No |
The version selector type. LABEL selects by tag. VERSION selects by specific version. Valid values:
|
LABEL |
| value |
string |
No |
The selector value. For LABEL, it is the tag name (such as latest). For VERSION, it 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 the AI Registry. |
code-review-template |
| version |
string |
Yes |
The version of the template in the AI Registry. |
1.0.0 |
| environment |
object |
No |
Optional. Credentials can be bound to both PLATFORM and RUNTIME model sources. When passing the object, you must explicitly provide a non-null credentialReferences list. Common environment variables are not supported. |
|
| credentialReferences |
array<object> |
No |
This list must be explicitly provided and cannot be null when the environment object is passed. The list is replaced as a whole. If environment is not passed during an update, the original binding is retained. If an empty list is passed or environment is null, the binding is cleared. Only the credential ID is passed, not the actual secret key. |
|
|
object |
No |
|||
| credentialId |
string |
No |
Required when a credential reference item is passed. Validated by the backend. |
cred-example |
| clientToken |
string |
No |
The reserved query parameter. The backend does not provide idempotency guarantees for deduplication or restoring the original acceptance result based on this identifier at this time. |
client-token-1 |
For the specific meanings and value requirements of the request parameters, see the following parameter description.
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The successful response for creating 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. A value of 200 indicates success. |
200 |
| code |
string |
The business status code. A value of SUCCESS indicates success. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
|
| data |
object |
The information about the created managed agent. |
|
| agentId |
string |
The ID of the managed agent. |
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. |
Code review agent running in the user environment |
| status |
string |
The status of the managed agent. Valid values:
Valid values:
|
Running |
| latestSpecVersion |
integer |
The latest specification version number. |
1 |
| latestVersionStatus |
string |
The processing status of the latest specification version. Valid values: pending (Pending), processing (Processing), waiting_retry (Waiting for retry), succeeded (Succeeded), failed (Failed), and superseded (Superseded by a new version). 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. Available only when modelSource is 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 the quota usage status for the current cycle. This parameter is empty if no quota is configured. |
|
| enabled |
boolean |
Indicates whether the quota is enabled. This parameter 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 cycle. |
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 parameter is read-only and returned by the backend. |
ACTIVE |
| usedAmount |
integer |
The number of tokens consumed in the current cycle. This parameter is read-only and returned by the backend. |
12345 |
| overLimit |
boolean |
Indicates whether the quota is exceeded in the current cycle. This parameter is read-only and returned by the backend. |
false |
| instruction |
string |
The agent instruction, 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 compatible 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. REFERENCE references the AI Registry. STATIC is statically provided with the deployment package. Valid values:
|
REFERENCE |
| versionSelector |
object |
The skill reference version selector. Supports LABEL tags and VERSION specific versions. Defaults to LABEL/latest if omitted. Selectors are not provided for STATIC sources. |
|
| type |
string |
The version selector type. LABEL selects by tag. VERSION selects by specific version. Valid values:
|
LABEL |
| value |
string |
The selector value. For LABEL, it is the tag name (such as latest). For VERSION, it is the specific version number. |
latest |
| fromTemplate |
boolean |
Specifies whether the skill is from a fixed template. This field is read-only. Template items cannot be removed. |
false |
| resolvedVersion |
string |
The current target version. This field is read-only. |
1.0.0 |
| appliedVersion |
string |
The effective runtime version. 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. REFERENCE references the AI Registry. STATIC is statically provided with the deployment package. Valid values:
|
REFERENCE |
| versionSelector |
object |
The skill reference version selector. Supports LABEL tags and VERSION specific versions. Defaults to LABEL/latest if omitted. Selectors are not provided for STATIC sources. |
|
| type |
string |
The version selector type. LABEL selects by tag. VERSION selects by specific version. Valid values:
|
LABEL |
| value |
string |
The selector value. For LABEL, it is the tag name (such as latest). For VERSION, it 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 the AI Registry. |
code-review-template |
| version |
string |
The version of the template in the 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 latest heartbeat is within 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 last heartbeat reported by the managed agent, in RFC 3339 format. |
2026-01-01T00:00:00Z |
| lastActiveAt |
string |
The last active time of the managed agent, 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> |
This list must be explicitly provided and cannot be null when the environment object is passed. The list is replaced as a whole. If environment is not passed during an update, the original binding is retained. If an empty list is passed or environment is null, the binding is cleared. Only the credential ID is passed, not the actual secret key. |
|
|
object |
|||
| credentialId |
string |
Required when a credential reference item is passed. Validated by the backend. |
cred-example |
For the meanings of the fields in a successful response, see the following response parameter description.
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.