- Ready-to-use tools: Vendor- or Runtime-provided capabilities (such as RAG retrieval) that require zero deployment.
- Sandboxed tools: Tools executed inside Browser/FileSystem or other sandboxes for controlled side effects.
Sandbox
AgentScope Runtime’s Sandbox is a versatile tool that provides a secure and isolated environment for a wide range of operations, including tool execution, browser automation, and file system operations. This tutorial will empower you to set up the tool sandbox dependency and run tools in an environment tailored to your specific needs.Prerequisites
The current sandbox supports multiple backend isolation/runtime options. For local usage, you can use Docker (optionally with gVisor) or BoxLite. For large-scale remote/production deployments, we recommend Kubernetes (K8s), Function Compute (FC), or Alibaba Cloud ACK. You can also switch the backend by setting the
CONTAINER_DEPLOYMENT environment variable (default: docker).- Docker (optionally with gVisor) or BoxLite (local)
- (Optional, remote/production, choose as needed) Kubernetes (K8s) / Function Compute (FC) / Alibaba Cloud ACK
Setup
Install Dependencies
First, install AgentScope Runtime:Prepare the Docker Images
The sandbox uses different Docker images for various functionalities. You can pull only the images you need or all of them for complete functionality:Option 1: Pull All Images (Recommended)
To ensure a complete sandbox experience with all features enabled, follow the steps below to pull and tag the necessary Docker images from our repository:All Docker images are hosted on Alibaba Cloud Container Registry (ACR) for optimal performance and reliability worldwide. Images are pulled from ACR and tagged with standard names for seamless integration with the AgentScope runtime environment.
Option 2: Pull Specific Images
Choose the images based on your specific needs:| Image | Purpose | When to Use |
|---|---|---|
| Base Image | Python code execution, shell commands | Essential for basic tool execution |
| GUI Image | Computer Use | When you need a graph UI |
| Filesystem Image | File system operations | When you need file read/write/management |
| Browser Image | Web browser automation | When you need web scraping or browser control |
| Mobile Image | Mobile operations | When you need to operate a mobile device |
| Training Image | Training and evaluating agent | Used for training and evaluating agent on some benchmark |
Verify Installation
You can verify that everything is set up correctly by callingrun_ipython_cell:
(Optional) Build the Docker Images from Scratch
If you prefer to build the Docker images yourself or need custom modifications, you can build them from scratch.Sandbox Usage
Create a Sandbox
The previous section introduced tool-centred usage methods, while this section introduces sandbox-centred usage methods. You can create different types of sandboxes via thesandbox SDK. AgentScope Runtime provides both synchronous and asynchronous versions for each sandbox type:
| Synchronous Class | Asynchronous Class |
|---|---|
BaseSandbox | BaseSandboxAsync |
GuiSandbox | GuiSandboxAsync |
FilesystemSandbox | FilesystemSandboxAsync |
BrowserSandbox | BrowserSandboxAsync |
MobileSandbox | MobileSandboxAsync |
TrainingSandbox | - |
AgentbaySandbox | - |
- Base Sandbox: Use for running Python code or shell commands in an isolated environment.
- GUI Sandbox: Provides a virtual desktop environment for mouse, keyboard, and screen operations.
- Filesystem Sandbox: A GUI-based sandbox with file system operations such as creating, reading, and deleting files.
- Browser Sandbox: A GUI-based sandbox with browser operations inside an isolated sandbox.
- Mobile Sandbox: A sandbox based on an Android emulator, allowing for mobile operations such as tapping, swiping, inputting text, and taking screenshots.
- TrainingSandbox: Sandbox for training and evaluation.
- AgentBay Sandbox (AgentbaySandbox): A cloud sandbox implementation based on AgentBay cloud service, supporting multiple image types (Linux, Windows, Browser, CodeSpace, Mobile, etc.).
No Local Docker Required
Fully cloud-based — no local Docker installation needed.
Multiple Environment Types
Supports Linux, Windows, Browser, CodeSpace, Mobile, and more.
Automatic Session Management
Session lifecycle is managed automatically.
Direct API Communication
Communicates directly with the AgentBay cloud service API.
More sandbox types are under development — stay tuned!
Add MCP Server to Sandbox
MCP (Model Context Protocol) is a standardised protocol that enables AI applications to securely connect to external data sources and tools. By integrating MCP servers into your sandbox, you can extend the sandbox’s capabilities with specialised tools and services without compromising security. The sandbox supports integrating MCP servers via theadd_mcp_servers method. Once added, you can discover available tools using list_tools and execute them with call_tool. Here’s an example of adding a time server that provides timezone-aware time functions:
Connect to Remote Sandbox
Remote deployment is beneficial for:
- Separating compute-intensive tasks to dedicated servers
- Multiple clients sharing the same sandbox environment
- Developing on resource-constrained local machines while executing on high-performance servers
- Deploying sandbox server with Kubernetes (K8s)
base_url:
Expose Sandbox as an MCP Server
Configure the local Sandbox Runtime as an MCP server namedsandbox, so it can be invoked by MCP-compatible clients to safely execute commands from the sandbox via a remote sandbox server http://127.0.0.1:8000.
Command Arguments
Theruntime-sandbox-mcp command accepts the following arguments:
| Argument | Values | Description |
|---|---|---|
--type | base, gui, browser, filesystem | Type of sandbox |
--base_url | URL string | Base URL of a remote sandbox service. Leave empty to run locally. |
--bearer_token | String token | Optional authentication token for secure access. |
Sandbox Service
Managing Sandboxes with SandboxService
SandboxService provides a unified sandbox management interface, enabling management of sandbox environments across different user sessions via session_id and user_id. Using SandboxService lets you better control a sandbox’s lifecycle and enables sandbox reuse.
Adding an MCP Server Using SandboxService
Connecting to a Remote Sandbox Using SandboxService
Tools
AgentScope Runtime embraces a componentized philosophy; instead of dropping you straight into API details, we start with the motivation. Tools give us a uniform, type-safe capsule for those accessories so they can plug into any orchestration framework without rewrites. Adding a tool is the recommended path whenever you need to expose a capability to multiple agents or execution engines. A tool carries its own IO schema, throttling policy, tracing hooks, and retry defaults, so you can register it as a tool for ReAct agents, feed it into LangGraph/MCP stacks, or publish it as an MCP server function. Teams typically introduce tools to solve recurring compliance constraints, encapsulate vendor APIs, or ship the same operation across on-call bots, copilots, and workflows. Once a capability is wrapped as a tool, you gain predictable behavior in a few common scenarios: orchestrators can reason about arguments up front, audit pipelines can log the same typed payloads, and platform teams can patch or swap implementations without touching agent prompts. In short, tools hide infrastructure churn while giving LLM-facing teams a clean interface.Why Tools (Key Features)
- Modular architecture: enterprise-grade functions stay decoupled, making it easy to compose or swap tools without touching the agent core.
- Framework integration: the same tool instances feed AgentScope Runtime, LangGraph, AutoGen, MCP, or bespoke frameworks, thanks to uniform schemas.
- ModelStudio alignment: tools wrap DashScope/ModelStudio services (Search, RAG, AIGC, Payments) with production-ready defaults, retries, and tracing.
- Type safety and observability: Pydantic models, async execution, and centralized validation mirror the production focus described in the original README.
- Clear benefits: consistent tool contracts, centralized governance, and faster onboarding for new agent teams because they reuse curated capabilities instead of reinventing integrations.
Tool Design Principles
- Single responsibility: each tool focuses on one enterprise capability (e.g., ModelStudio Search, Alipay refund) so it can be composed with other tools without hidden side effects.
- Typed boundaries: tools declare Pydantic
*Inputand*Outputmodels so arguments/results are validated before any network call and so function schemas can be generated automatically. - Adapter friendly: the shared
Toolbase emits OpenAI-compatiblefunction_schema, allowing adapters (AgentScope, LangGraph, AutoGen, MCP, etc.) to expose tools with zero additional glue. - Async-first, sync-friendly:
_arunis always async for throughput, whilerun()bridges into sync contexts, just like the examples demonstrate for components. - Observability-ready: because every invocation funnels through the base class, runtime tracing, retries, and logging can be added centrally without touching individual tools.
Tool Class Essentials
Core capabilities
- Input/output enforcement:
Toolcaptures the genericToolArgsT/ToolReturnTtypes, validates runtime arguments, and ensures the return payload matches the declared schema. - Automatic function schema: the base class inspects the Pydantic model and publishes a
FunctionToolschema so LLM tool-calling stacks know exactly how to call the tool. - Async + sync execution: call
await tool.arun(...)inside async workflows ortool.run(...)when you only have a synchronous context; both paths share the same validation. - Argument helpers:
Tool.verify_args()/verify_list_args()parse JSON strings or dicts into typed inputs, making it easy to deserialize persisted tool calls. - Stringified outputs:
return_value_as_string()provides deterministic serialization for audit logs and adapters that require string outputs.
Custom Tool Development Example
Tool, implement _arun, instantiate once, and pass the instance into whichever agent framework you use.
AgentScope Integration Example
We useagentscope_tool_adapter to add tools to AgentScope’s Toolkit:
Using Tools inside Agents
- Configure credentials: declare environment variables (DashScope keys, Alipay secrets, etc.) before running the agent process so tools can authenticate.
- Instantiate once: create tool objects during agent initialization; reuse them instead of re-instantiating per call to keep connections warm.
- Prepare payloads: build dictionaries or Pydantic instances that match the documented
*Inputmodel. When calling from LLM tool invocations, rely on the generated schema to keep arguments consistent. - Call asynchronously: prefer
await tool.arun(input_model); only userun()in synchronous contexts. - Consume structured outputs: each result is a typed model (e.g.,
SearchOutput,RagOutput,PaymentOutput)—store them directly or convert withreturn_value_as_string()for persistence. - Integrate via adapters: the runtime already provides adapters for AgentScope, LangGraph, MCP, etc. Simply hand over
tool.function_schema(or the tool instance itself, depending on the adapter) to wire the capability into your workflow.
Built-in Tool Families
Each family bundles a set of related ModelStudio or partner services. Refer to the detailed cookbook pages for exhaustive parameter tables, examples, and operational notes.ModelStudio Search Tools
- Key tools:
ModelstudioSearch,ModelstudioSearchLite(agentscope_runtime.tools.searches). - When to use: semantic/metasearch across web, news, academic, product, multimedia sources, with advanced routing, filtering, and caching. The Lite version trades configurability for lower latency and resource savings.
- Usage highlights: supply
messagesplussearch_optionsdict (strategy,max_results,time_range, etc.), optionally addsearch_output_rulesfor citations/summaries, and read backsearch_result+search_info.
ModelStudio RAG Tools
- Key tools:
ModelstudioRag,ModelstudioRagLite(agentscope_runtime.common.tools.RAGs). - When to use: ground answers in DashScope knowledge bases with dense/sparse/hybrid retrieval, multi-turn context fusion, multimodal inputs, and citation-friendly generation.
- Usage highlights: pass the dialogue
messages,rag_options(knowledge_base_id,top_k,score_threshold,enable_citation), plus authentication tokens; consumerag_result.answer,references, andconfidence.
ModelStudio AIGC (Generations) Tools
- Key tools:
ImageGeneration,ImageEdit,ImageStyleRepaintand the WAN/Qwen variants underagentscope_runtime.tools.generations. - When to use: text-to-image creation, image editing (in/out-painting, replacements), and portrait style transfer with DashScope WanXiang or Qwen media models.
- Usage highlights: supply prompts plus optional
size/n, or providebase_image_url+mask_image_urlfor edits; outputs are signed asset URLs—download or proxy them promptly.
Alipay Payment & Subscription Tools
- Key tools (from
agentscope_runtime.tools.alipay):MobileAlipayPayment,WebPageAlipayPayment,AlipayPaymentQuery,AlipayPaymentRefund,AlipayRefundQuery,AlipaySubscribeStatusCheck,AlipaySubscribePackageInitialize,AlipaySubscribeTimesSave,AlipaySubscribeCheckOrInitialize. - When to use: orchestrate full payment lifecycles (link creation, status checks, refunds) and manage subscription entitlements or pay-per-use deductions inside enterprise agents.
- Usage highlights: payment tools accept
out_trade_no,order_title,total_amount; query/refund tools operate on order IDs plus optionalout_request_no; subscription tools pivot on useruuidand return flags, packages, or subscription URLs.