Sandbox Module

The sandbox module provides isolated environments for running code securely.

Public Interface

The main classes that users typically interact with are directly importable from the agentscope_runtime.sandbox package:

BaseSandbox

class agentscope_runtime.sandbox.BaseSandbox(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None)[source]

Bases: Sandbox

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

__init__(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None)[source]

Initialize the sandbox interface.

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

run_ipython_cell(code)[source]
Parameters:

code (str)

run_shell_command(command)[source]
Parameters:

command (str)

BrowserSandbox

class agentscope_runtime.sandbox.BrowserSandbox(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None)[source]

Bases: Sandbox

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

__init__(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None)[source]

Initialize the sandbox interface.

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

property browser_ws
browser_close()[source]
browser_resize(width, height)[source]
Parameters:
browser_console_messages()[source]
browser_handle_dialog(accept, prompt_text='')[source]
Parameters:
browser_file_upload(paths)[source]
Parameters:

paths (list)

browser_press_key(key)[source]
Parameters:

key (str)

browser_navigate(url)[source]
Parameters:

url (str)

browser_navigate_back()[source]
browser_navigate_forward()[source]
browser_network_requests()[source]
browser_pdf_save(filename='')[source]
Parameters:

filename (str)

browser_take_screenshot(raw=False, filename='', element='', ref='')[source]
Parameters:
browser_snapshot()[source]
browser_click(element, ref)[source]
Parameters:
browser_drag(start_element, start_ref, end_element, end_ref)[source]
Parameters:

  • start_element (str)

  • start_ref (str)

  • end_element (str)

  • end_ref (str)

browser_hover(element, ref)[source]
Parameters:
browser_type(element, ref, text, submit=False, slowly=False)[source]
Parameters:
browser_select_option(element, ref, values)[source]
Parameters:
browser_tab_list()[source]
browser_tab_new(url='')[source]
Parameters:

url (str)

browser_tab_select(index)[source]
Parameters:

index (int)

browser_tab_close(index=None)[source]
Parameters:

index (int | None)

browser_wait_for(time=None, text=None, text_gone=None)[source]
Parameters:

  • time (float | None)

  • text (str | None)

  • text_gone (str | None)

FilesystemSandbox

class agentscope_runtime.sandbox.FilesystemSandbox(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None)[source]

Bases: Sandbox

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

__init__(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None)[source]

Initialize the sandbox interface.

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

read_file(path)[source]
Parameters:

path (str)

read_multiple_files(paths)[source]
Parameters:

paths (list)

write_file(path, content)[source]
Parameters:
edit_file(path, edits, dry_run=False)[source]
Parameters:
create_directory(path)[source]
Parameters:

path (str)

list_directory(path)[source]
Parameters:

path (str)

directory_tree(path)[source]
Parameters:

path (str)

move_file(source, destination)[source]
Parameters:

  • source (str)

  • destination (str)

search_files(path, pattern, exclude_patterns=[])[source]
Parameters:

  • path (str)

  • pattern (str)

  • exclude_patterns (list)

get_file_info(path)[source]
Parameters:

path (str)

list_allowed_directories()[source]

TrainingSandbox

class agentscope_runtime.sandbox.TrainingSandbox(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None, box_type=SandboxType.APPWORLD)[source]

Bases: Sandbox

Training Sandbox class for managing and executing training-related tasks.

This class provides methods to create, manage, and interact with training environment instances using specialized tool calls.

Parameters:

  • sandbox_id (str | None)

  • timeout (int)

  • base_url (str | None)

  • bearer_token (str | None)

  • box_type (SandboxType)

__init__(sandbox_id=None, timeout=3000, base_url=None, bearer_token=None, box_type=SandboxType.APPWORLD)[source]

Initialize the Training Sandbox.

Parameters:

  • sandbox_id (Optional[str]) – Unique identifier for the sandbox.

  • timeout (int) – Maximum time allowed for sandbox operations.

  • base_url (Optional[str]) – Base URL for sandbox API.

  • bearer_token (Optional[str]) – Authentication token for API access.

  • box_type (SandboxType)

create_instance(env_type, task_id, instance_id=None, params=None)[source]

Create a new instance of a training environment.

Parameters:

  • env_type (str) – Type of environment to create.

  • task_id (str) – Identifier for the specific task.

  • instance_id (str, optional) – Custom instance identifier.

  • params (Dict, optional) – Additional parameters for instance creation.

Returns:

The created instance details.

get_task_ids(env_type, split='train', params=None)[source]

Retrieve task identifiers for a specific environment.

Parameters:

  • env_type (str) – Type of environment.

  • split (str, optional) – Data split to retrieve tasks from. Defaults to “train”.

  • params (dict, optional) – Additional filtering parameters.

Returns:

List of task identifiers.

get_env_profile(env_type, split='train', params=None)[source]

Retrieve the environment profile.

Parameters:

  • env_type (str) – Type of environment.

  • split (str, optional) – Data split to retrieve profile from. Defaults to “train”.

  • params (dict, optional) – Additional profile retrieval parameters.

Returns:

Environment profile details.

step(instance_id, action=None, params=None)[source]

Execute a step in the training environment.

Parameters:

  • instance_id (str) – Identifier of the environment instance.

  • action (Dict, optional) – Action to be performed in the environment.

  • params (Dict, optional) – Additional step parameters.

Returns:

Result of the step execution.

Return type:

str

evaluate(instance_id, messages=None, params=None)[source]

Evaluate the performance of a training environment instance.

Parameters:

  • instance_id (str) – Identifier of the environment instance.

  • messages (Dict, optional) – Evaluation-related messages.

  • params (Dict, optional) – Additional evaluation parameters.

Returns:

Evaluation results.

release_instance(instance_id)[source]

Release a training environment instance.

Parameters:

instance_id (str) – Identifier of the instance to be released.

Returns:

Result of the instance release operation.