agentscope-runtime 1.0.5.post1__py3-none-any.whl → 1.1.0b2__py3-none-any.whl

agentscope_runtime/engine/runner.py

@@ -14,6 +14,7 @@ from typing import (
     Union,
     Dict,
     AsyncIterator,
+    Callable,
 )
 
 from .deployers import (
@@ -49,6 +50,9 @@ class Runner:
         """
         self.framework_type = None
 
+        self.in_type_converters: Optional[Dict[str, Callable]] = None
+        self.out_type_converters: Optional[Dict[str, Callable]] = None
+
         self._deploy_managers = {}
         self._health = False
         self._exit_stack = AsyncExitStack()
@@ -77,7 +81,7 @@ class Runner:
             else:
                 init_fn()
         else:
-            logger.warning("[Runner] init_handler is not callable")
+            logger.warning("init_handler is not callable")
         self._health = True
         return self
 
@@ -90,7 +94,7 @@ class Runner:
                 else:
                     shutdown_fn()
         except Exception as e:
-            logger.warning(f"[Runner] Exception in shutdown handler: {e}")
+            logger.warning(f"Exception in shutdown handler: {e}")
         try:
             await self._exit_stack.aclose()
         except Exception:
@@ -251,7 +255,12 @@ class Runner:
 
             stream_adapter = adapt_agentscope_message_stream
             kwargs.update(
-                {"msgs": message_to_agentscope_msg(request.input)},
+                {
+                    "msgs": message_to_agentscope_msg(
+                        request.input,
+                        type_converters=self.in_type_converters,
+                    ),
+                },
             )
         elif self.framework_type == "langgraph":
             from ..adapters.langgraph.stream import (
@@ -261,7 +270,12 @@ class Runner:
 
             stream_adapter = adapt_langgraph_message_stream
             kwargs.update(
-                {"msgs": message_to_langgraph_msg(request.input)},
+                {
+                    "msgs": message_to_langgraph_msg(
+                        request.input,
+                        type_converters=self.in_type_converters,
+                    ),
+                },
             )
         elif self.framework_type == "agno":
             from ..adapters.agno.stream import (
@@ -271,7 +285,12 @@ class Runner:
 
             stream_adapter = adapt_agno_message_stream
             kwargs.update(
-                {"msgs": await message_to_agno_message(request.input)},
+                {
+                    "msgs": await message_to_agno_message(
+                        request.input,
+                        type_converters=self.in_type_converters,
+                    ),
+                },
             )
         elif self.framework_type == "ms_agent_framework":
             from ..adapters.ms_agent_framework.stream import (
@@ -283,7 +302,12 @@ class Runner:
 
             stream_adapter = adapt_ms_agent_framework_message_stream
             kwargs.update(
-                {"msgs": message_to_ms_agent_framework_message(request.input)},
+                {
+                    "msgs": message_to_ms_agent_framework_message(
+                        request.input,
+                        type_converters=self.in_type_converters,
+                    ),
+                },
             )
         # TODO: support other frameworks
         else:
@@ -303,6 +327,7 @@ class Runner:
                     **query_kwargs,
                     **kwargs,
                 ),
+                type_converters=self.out_type_converters,
             ):
                 if (
                     event.status == RunStatus.Completed

agentscope_runtime/engine/schemas/agent_schemas.py

@@ -49,6 +49,7 @@ class ContentType:
     AUDIO = "audio"
     FILE = "file"
     REFUSAL = "refusal"
+    VIDEO = "video"
 
 
 class Role:
@@ -231,6 +232,24 @@ class McpApprovalRequest(BaseModel):
     """The label of the mcp server making the request."""
 
 
+class McpApprovalResponse(BaseModel):
+    """
+    mcp approval response
+    """
+
+    approval_request_id: str
+    """The unique ID of the approval request."""
+
+    approve: bool
+    """Whether the request was approved."""
+
+    id: Optional[str] = None
+    """The unique ID of the approval response."""
+
+    reason: Optional[str] = None
+    """Optional reason for the decision."""
+
+
 class Error(BaseModel):
     code: str
     """The error code of the message."""
@@ -383,6 +402,14 @@ class AudioContent(Content):
     """
 
 
+class VideoContent(Content):
+    type: Literal[ContentType.VIDEO] = ContentType.VIDEO
+    """The type of the content part."""
+
+    video_url: Optional[str] = None
+    """The video URL details."""
+
+
 class FileContent(Content):
     type: Literal[ContentType.FILE] = ContentType.FILE
     """The type of the content part."""
@@ -442,6 +469,7 @@ AgentContent = Annotated[
         AudioContent,
         FileContent,
         RefusalContent,
+        VideoContent,
     ],
     Field(discriminator="type"),
 ]

agentscope_runtime/engine/services/sandbox/sandbox_service.py

@@ -9,11 +9,41 @@ from ....engine.services.base import ServiceWithLifecycleManager
 
 
 class SandboxService(ServiceWithLifecycleManager):
-    def __init__(self, base_url=None, bearer_token=None):
+    def __init__(
+        self,
+        base_url=None,
+        bearer_token=None,
+        drain_on_stop: bool = True,
+    ):
+        """
+        Create a SandboxService.
+
+        Args:
+            base_url:
+                Sandbox manager API base URL. If None, runs in embedded mode.
+            bearer_token:
+                Bearer token used to authenticate with the sandbox manager API.
+            drain_on_stop:
+                Whether to drain (release) all sandboxes associated with this
+                service instance when `stop()` is called.
+
+                - True (default): `stop()` will iterate over all known session
+                  mappings and release all non-AgentBay sandbox environments.
+                  This helps prevent resource leaks when the service shuts
+                  down.
+                - False: `stop()` will NOT release sessions/environments. Use
+                  this when sandboxes are meant to outlive the service process
+                  (e.g., managed elsewhere).
+
+                Note: In embedded mode (`base_url is None`), `stop()` will
+                  still  call `manager_api.cleanup()` to tear down embedded
+                  resources.
+        """
         self.manager_api = None
         self.base_url = base_url
         self.bearer_token = bearer_token
         self._health = False
+        self.drain_on_stop = drain_on_stop
 
     async def start(self) -> None:
         if self.manager_api is None:
@@ -29,14 +59,16 @@ class SandboxService(ServiceWithLifecycleManager):
             self._health = False
             return
 
-        session_keys = self.manager_api.list_session_keys()
-
-        if session_keys:
-            for session_ctx_id in session_keys:
-                env_ids = self.manager_api.get_session_mapping(session_ctx_id)
-                if env_ids:
-                    for env_id in env_ids:
-                        self.manager_api.release(env_id)
+        if self.drain_on_stop:
+            session_keys = self.manager_api.list_session_keys()
+            if session_keys:
+                for session_ctx_id in session_keys:
+                    env_ids = self.manager_api.get_session_mapping(
+                        session_ctx_id,
+                    )
+                    if env_ids:
+                        for env_id in env_ids:
+                            self.manager_api.release(env_id)
 
         if self.base_url is None:
             # Embedded mode

agentscope_runtime/sandbox/box/base/base_sandbox.py

@@ -23,6 +23,7 @@ class BaseSandbox(Sandbox):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.BASE,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -30,6 +31,7 @@ class BaseSandbox(Sandbox):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     def run_ipython_cell(self, code: str):
@@ -66,6 +68,7 @@ class BaseSandboxAsync(SandboxAsync):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.BASE_ASYNC,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -73,6 +76,7 @@ class BaseSandboxAsync(SandboxAsync):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     async def run_ipython_cell(self, code: str):

agentscope_runtime/sandbox/box/browser/browser_sandbox.py

@@ -43,6 +43,7 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.BROWSER,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -50,6 +51,7 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     def browser_close(self):
@@ -316,6 +318,7 @@ class BrowserSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.BROWSER_ASYNC,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -323,6 +326,7 @@ class BrowserSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     async def browser_close(self):

agentscope_runtime/sandbox/box/dummy/dummy_sandbox.py

@@ -22,6 +22,13 @@ class DummySandbox(Sandbox):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.DUMMY,
+        workspace_dir: Optional[str] = None,
     ):
-        self._sandbox_id = sandbox_id
-        self.sandbox_type = sandbox_type
+        super().__init__(
+            sandbox_id,
+            timeout,
+            base_url,
+            bearer_token,
+            sandbox_type,
+            workspace_dir,
+        )

agentscope_runtime/sandbox/box/filesystem/filesystem_sandbox.py

@@ -25,6 +25,7 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.FILESYSTEM,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -32,6 +33,7 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     def read_file(self, path: str):
@@ -171,6 +173,7 @@ class FilesystemSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.FILESYSTEM_ASYNC,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -178,6 +181,7 @@ class FilesystemSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     async def read_file(self, path: str):

agentscope_runtime/sandbox/box/gui/gui_sandbox.py

@@ -77,6 +77,7 @@ class GuiSandbox(GUIMixin, BaseSandbox):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.GUI,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -84,8 +85,9 @@ class GuiSandbox(GUIMixin, BaseSandbox):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
-        if get_platform() == "linux/arm64":
+        if "arm" in get_platform():
             logger.warning(
                 "\nCompatibility Notice: This GUI Sandbox may have issues on "
                 "arm64 CPU architectures, due to the computer-use-mcp does "
@@ -166,6 +168,7 @@ class GuiSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.GUI_ASYNC,
+        workspace_dir: Optional[str] = None,
     ):
         super().__init__(
             sandbox_id,
@@ -173,6 +176,7 @@ class GuiSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
         # Architecture compatibility warning
         if get_platform() == "linux/arm64":

agentscope_runtime/sandbox/box/mobile/mobile_sandbox.py

@@ -197,6 +197,7 @@ class MobileSandbox(MobileMixin, Sandbox):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.MOBILE,
+        workspace_dir: Optional[str] = None,
     ):
         if base_url is None and not self.__class__._host_check_done:
             _check_host_readiness()
@@ -208,6 +209,7 @@ class MobileSandbox(MobileMixin, Sandbox):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     def adb_use(
@@ -346,6 +348,7 @@ class MobileSandboxAsync(MobileMixin, AsyncMobileMixin, SandboxAsync):
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.MOBILE_ASYNC,
+        workspace_dir: Optional[str] = None,
     ):
         if base_url is None and not self.__class__._host_check_done:
             _check_host_readiness()
@@ -357,6 +360,7 @@ class MobileSandboxAsync(MobileMixin, AsyncMobileMixin, SandboxAsync):
             base_url,
             bearer_token,
             sandbox_type,
+            workspace_dir,
         )
 
     async def adb_use(

agentscope_runtime/sandbox/box/sandbox.py

@@ -4,18 +4,51 @@ import logging
 import signal
 from typing import Any, Optional
 
+import shortuuid
+
 from ..enums import SandboxType
 from ..manager.sandbox_manager import SandboxManager
 from ..manager.server.app import get_config
 
 
-logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
 class SandboxBase:
     """
     Common base class for both sync and async Sandbox interfaces.
+
+    This class holds shared configuration and lifecycle behaviors used by
+    `Sandbox` (sync) and `SandboxAsync` (async). It can operate in:
+
+    - Embedded mode: `base_url` is not provided; a local `SandboxManager`
+      is used.
+    - Remote mode: `base_url` is provided; operations are delegated to a remote
+      `SandboxManager` over HTTP.
+
+    Args:
+        sandbox_id: Existing sandbox/container identifier to attach to. If not
+            provided, a new sandbox will be created when entering the context
+            manager.
+        timeout: HTTP request timeout in seconds for client-side calls to the
+            sandbox runtime/manager (e.g., `list_tools`, `call_tool`, and other
+            network requests). This parameter does not control sandbox idle,
+            recycle, or heartbeat timeouts, which are configured separately by
+            the sandbox runtime (for example via the `HEARTBEAT_TIMEOUT`
+            environment variable).
+        base_url: Remote SandboxManager service URL. If provided, the sandbox
+            runs in remote mode; otherwise, embedded mode is used.
+        bearer_token: Optional bearer token for authenticating to the remote
+            manager.
+        sandbox_type: Sandbox runtime type/image selection.
+
+    Attributes:
+        base_url: Remote manager URL, if any.
+        embed_mode: Whether the sandbox is running with an embedded local
+            manager.
+        sandbox_type: Selected sandbox type.
+        timeout: HTTP request timeout in seconds.
+        _sandbox_id: The bound sandbox id (may be None until created).
     """
 
     def __init__(
@@ -25,12 +58,22 @@ class SandboxBase:
         base_url: Optional[str] = None,
         bearer_token: Optional[str] = None,
         sandbox_type: SandboxType = SandboxType.BASE,
+        workspace_dir: Optional[str] = None,
     ) -> None:
         self.base_url = base_url
         self.embed_mode = not bool(base_url)
         self.sandbox_type = sandbox_type
         self.timeout = timeout
         self._sandbox_id = sandbox_id
+        self._warned_sandbox_not_started = False
+
+        self.workspace_dir = workspace_dir
+
+        if self.base_url and self.workspace_dir:
+            raise RuntimeError(
+                "workspace_dir is only supported in embedded(local) mode; "
+                "remote mode mounts server paths and is not allowed.",
+            )
 
         if base_url:
             # Remote Manager
@@ -40,13 +83,24 @@ class SandboxBase:
             )
         else:
             # Embedded Manager
+            config = get_config()
+            # Allow in embedded mode
+            config.allow_mount_dir = True
             self.manager_api = SandboxManager(
-                config=get_config(),
+                config=config,
                 default_type=sandbox_type,
             )
 
     @property
     def sandbox_id(self) -> Optional[str]:
+        if self._sandbox_id is None and not self._warned_sandbox_not_started:
+            self._warned_sandbox_not_started = True
+            logger.error(
+                "Sandbox is not started yet (sandbox_id is None). "
+                "Use `with Sandbox(...) as sandbox:` / "
+                "`async with SandboxAsync(...) as sandbox:` "
+                "or call `start() / start_async()` first.",
+            )
         return self._sandbox_id
 
     @sandbox_id.setter
@@ -101,12 +155,33 @@ class SandboxBase:
 class Sandbox(SandboxBase):
     def __enter__(self):
         # Create sandbox if sandbox_id not provided
-        if self.sandbox_id is None:
-            self.sandbox_id = self.manager_api.create_from_pool(
-                sandbox_type=SandboxType(self.sandbox_type).value,
-            )
-            if self.sandbox_id is None:
-                raise RuntimeError("No sandbox available.")
+        if self._sandbox_id is None:
+            short_uuid = shortuuid.ShortUUID().uuid()
+            session_ctx_id = str(short_uuid)
+            if self.workspace_dir:
+                # bypass pool when workspace_dir is set
+                _id = self.manager_api.create(
+                    sandbox_type=SandboxType(self.sandbox_type).value,
+                    mount_dir=self.workspace_dir,
+                    # TODO: support bind self-define id
+                    meta={"session_ctx_id": session_ctx_id},
+                )
+            else:
+                _id = self.manager_api.create_from_pool(
+                    sandbox_type=SandboxType(self.sandbox_type).value,
+                    # TODO: support bind self-define id
+                    meta={"session_ctx_id": session_ctx_id},
+                )
+
+            self._sandbox_id = _id
+
+            if self._sandbox_id is None:
+                raise RuntimeError(
+                    "No sandbox available. This may happen if: "
+                    "(1) the sandbox pool is exhausted, "
+                    "(2) max sandbox instances limit has been reached, or "
+                    "(3) sandbox container startup failed. ",
+                )
             if self.embed_mode:
                 atexit.register(self._cleanup)
                 self._register_signal_handlers()
@@ -115,6 +190,14 @@ class Sandbox(SandboxBase):
     def __exit__(self, exc_type, exc_value, traceback):
         self._cleanup()
 
+    def start(self) -> "Sandbox":
+        """Explicitly start sandbox without context manager."""
+        return self.__enter__()
+
+    def close(self) -> None:
+        """Explicitly cleanup sandbox without context manager."""
+        self.__exit__(None, None, None)
+
     def get_info(self) -> dict:
         return self.manager_api.get_info(self.sandbox_id)
 
@@ -143,11 +226,26 @@ class Sandbox(SandboxBase):
 
 class SandboxAsync(SandboxBase):
     async def __aenter__(self):
-        if self.sandbox_id is None:
-            self.sandbox_id = await self.manager_api.create_from_pool_async(
-                sandbox_type=SandboxType(self.sandbox_type).value,
-            )
-            if self.sandbox_id is None:
+        if self._sandbox_id is None:
+            short_uuid = shortuuid.ShortUUID().uuid()
+            session_ctx_id = str(short_uuid)
+            if self.workspace_dir:
+                _id = await self.manager_api.create_async(
+                    sandbox_type=SandboxType(self.sandbox_type).value,
+                    mount_dir=self.workspace_dir,
+                    # TODO: support bind self-define id
+                    meta={"session_ctx_id": session_ctx_id},
+                )
+            else:
+                _id = await self.manager_api.create_from_pool_async(
+                    sandbox_type=SandboxType(self.sandbox_type).value,
+                    # TODO: support bind self-define id
+                    meta={"session_ctx_id": session_ctx_id},
+                )
+
+            self._sandbox_id = _id
+
+            if self._sandbox_id is None:
                 raise RuntimeError("No sandbox available.")
             if self.embed_mode:
                 atexit.register(self._cleanup)
@@ -157,6 +255,14 @@ class SandboxAsync(SandboxBase):
     async def __aexit__(self, exc_type, exc_value, traceback):
         await self._cleanup_async()
 
+    async def start_async(self) -> "SandboxAsync":
+        """Explicitly start sandbox without async context manager."""
+        return await self.__aenter__()
+
+    async def close_async(self) -> None:
+        """Explicitly cleanup sandbox without async context manager."""
+        await self.__aexit__(None, None, None)
+
     async def _cleanup_async(self):
         try:
             if self.embed_mode:
@@ -171,6 +277,9 @@ class SandboxAsync(SandboxBase):
                 f"\n{traceback.format_exc()}",
             )
 
+    def get_info(self) -> dict:
+        return self.manager_api.get_info(self.sandbox_id)
+
     async def get_info_async(self) -> dict:
         return await self.manager_api.get_info_async(self.sandbox_id)
 

agentscope_runtime/sandbox/client/async_http_client.py

@@ -10,6 +10,7 @@ from pydantic import Field
 from .base import SandboxHttpBase
 from ..model import ContainerModel
 
+logging.getLogger("httpx").setLevel(logging.WARNING)
 logger = logging.getLogger(__name__)
 
 

agentscope_runtime/sandbox/client/base.py

@@ -4,7 +4,6 @@ from urllib.parse import urljoin
 
 DEFAULT_TIMEOUT = 60
 
-logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 

agentscope_runtime/sandbox/client/http_client.py

@@ -13,8 +13,6 @@ from ..model import ContainerModel
 
 DEFAULT_TIMEOUT = 60
 
-logging.getLogger("httpx").setLevel(logging.CRITICAL)
-logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)