Skip to main content

Delete agent

Delete an agent configuration; existing sessions keep the snapshot created with the session and are not affected.

Endpoint

DELETE /agents/{agent_id} Returns 200 and a delete envelope. Deletion is a soft archive: the agent is marked as deleted and a deletion time is recorded. Later retrieve or delete requests return 404. Deletion only archives the agent. It does not stop existing sessions or clean up environments. Existing sessions keep the agent snapshot created with the session and are not affected by the deletion.

Path parameters

agent_id string (required)Agent ID. Treat it as an opaque stringThis endpoint has no request body or query parameters.

Request example

curl -sS -X DELETE "$BASE_URL/agents/agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

Response fields

id stringID of the deleted agentobject stringAgent deletion result object type, fixed as agent.deleteddeleted booleanWhether deletion succeeded, true when deletion succeeds

Response example

{
  "id": "agent_xxx",
  "object": "agent.deleted",
  "deleted": true
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorUse an agent ID that exists and has not been deleted in the current workspace
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id