DeleteExternalAgent
Deletes a managed agent from a specified workspace and asynchronously cleans up its associated platform resources.
Operation description
Deletes a managed agent from a specified workspace and asynchronously cleans up its associated platform resources.
Prerequisites
The workspace must be writable. If the agent is still associated with a team, dissociate it from the team first.
Deletion results
A successful response indicates that the deletion request has been accepted, and the response summary is typically status=Deleting. If the agent is already being deleted, a subsequent request returns the current summary.
Call GetExternalAgent to query the deletion progress. After the deletion is complete, a details query returns a resource not found error. The processes and runtime environments of managed agents are managed by the caller.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:DeleteExternalAgent |
delete |
*ExternalAgent
|
None | None |
Request syntax
DELETE /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 ID of the managed agent. |
agent-1 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
No parameters required.
For the definitions and value requirements of request parameters, see the following parameter descriptions.
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The successful response for deleting a managed agent. |
||
| requestId |
string |
The request ID. |
1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| message |
string |
The request 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 summary information of the deleted managed agent. |
|
| agentId |
string |
The ID of the managed agent. |
agent-1 |
| workspaceId |
string |
The workspace ID. |
ws-1 |
| 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: Creating, Running, Failed, Updating, Deleting, and Deleted. Valid values:
|
Running |
| latestSpecVersion |
integer |
The latest specification version. |
1 |
| createMode |
string |
The creation mode. |
CUSTOM |
| runtime |
string |
The runtime type reported by the managed agent. |
qwenpaw |
| deployType |
string |
The deployment type. |
SELF_HOSTED |
| accessMode |
string |
The inbound access method. Valid values:
|
API_KEY |
| accessScope |
string |
The user access scope. Valid values:
|
ALL |
| 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 |
For the definitions of fields in a successful response, see the following response parameter descriptions.
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",
"name": "my-external-agent",
"description": "Code review agent running in the user environment",
"status": "Running",
"latestSpecVersion": 1,
"createMode": "CUSTOM",
"runtime": "qwenpaw",
"deployType": "SELF_HOSTED",
"accessMode": "API_KEY",
"accessScope": "ALL",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
}
}
Error codes
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.