change method name and add docstring

src/ai/backend/agent/agent.py

@@ -1625,7 +1625,7 @@ async def pull_image(
         """
 
     @abstractmethod
-    async def pull_image_in_background(
+    async def pull_image_with_stream(
         self,
         image_ref: ImageRef,
         registry_conf: ImageRegistry,
@@ -1634,9 +1634,20 @@ async def pull_image_in_background(
         timeout: Optional[float] = None,
     ) -> None:
         """
-        Pull the given image from the given registry.
-        Read the streaming response and report through the given ProgressReporter.
-        Return `None` if the pull task is successfully completed. Else, return an error message.
+        Pull an image with streaming output from a registry.
+        Stream the pull operation response and report progress through a ProgressReporter.
+
+        Args:
+            image_ref (ImageRef): The image name and tag to pull
+            registry_conf (ImageRegistry): The image registry configuration
+            reporter (Optional[ProgressReporter]): The progress reporter instance. If None, progress won't be reported
+            timeout (Optional[float]): The pull timeout
+
+        Returns:
+            None
+
+        Raises:
+            ImagePullFailure: If the pull operation fails or returns error messages
         """
 
     @abstractmethod

src/ai/backend/agent/docker/agent.py

@@ -83,7 +83,7 @@
 from ai.backend.logging.formatter import pretty
 
 from ..agent import ACTIVE_STATUS_SET, AbstractAgent, AbstractKernelCreationContext, ComputerContext
-from ..exception import ContainerCreationError, UnsupportedResource
+from ..exception import ContainerCreationError, ImagePullFailure, UnsupportedResource
 from ..fs import create_scratch_filesystem, destroy_scratch_filesystem
 from ..kernel import AbstractKernel, KernelFeatures
 from ..proxy import DomainSocketProxy, proxy_connection
@@ -1513,14 +1513,15 @@ async def pull_image(
         async with closing_async(Docker()) as docker:
             await docker.images.pull(image_ref.canonical, auth=auth_config, timeout=timeout)
 
-    async def pull_image_in_background(
+    async def pull_image_with_stream(
         self,
         image_ref: ImageRef,
         registry_conf: ImageRegistry,
         *,
         reporter: Optional[ProgressReporter] = None,
         timeout: Optional[float] = None,
     ) -> None:
+        err_msg: Optional[str] = None
         auth_config = None
         reg_user = registry_conf.get("username")
         reg_passwd = registry_conf.get("password")
@@ -1708,6 +1709,7 @@ async def handle_err_response(resp: PullErrorResponse) -> None:
                             else:
                                 await handle_response(_resp, layer_ids)
                         case dict() if resp.get("error"):
+                            err_msg = str(resp["error"])
                             await handle_err_response(
                                 PullErrorResponse(
                                     error=resp["error"],
@@ -1718,6 +1720,8 @@ async def handle_err_response(resp: PullErrorResponse) -> None:
                             raise KeyError
                 except KeyError:
                     log.warning(f"Unable to deserialize pulling response. skip. (resp:{str(resp)})")
+        if err_msg is not None:
+            raise ImagePullFailure(err_msg)
 
     async def check_image(
         self, image_ref: ImageRef, image_id: str, auto_pull: AutoPullBehavior

src/ai/backend/agent/dummy/agent.py

@@ -291,7 +291,7 @@ async def pull_image(
         delay = self.dummy_agent_cfg["delay"]["pull-image"]
         await asyncio.sleep(delay)
 
-    async def pull_image_in_background(
+    async def pull_image_with_stream(
         self,
         image_ref: ImageRef,
         registry_conf: ImageRegistry,

src/ai/backend/agent/kubernetes/agent.py

@@ -1024,7 +1024,7 @@ async def pull_image(
         # TODO: Add support for appropriate image pulling mechanism on K8s
         pass
 
-    async def pull_image_in_background(
+    async def pull_image_with_stream(
         self,
         image_ref: ImageRef,
         registry_conf: ImageRegistry,

src/ai/backend/agent/server.py

@@ -524,7 +524,7 @@ async def _pull(reporter: ProgressReporter, *, img_conf: ImageConfig) -> None:
                     Optional[float], self.local_config["agent"]["api"]["pull-timeout"]
                 )
                 try:
-                    await self.agent.pull_image_in_background(
+                    await self.agent.pull_image_with_stream(
                         img_ref, img_conf["registry"], reporter=reporter, timeout=image_pull_timeout
                     )
                 except asyncio.TimeoutError: