接口interface io.agentscope.harness.agent.sandbox 2.x

Sandbox

public interface Sandbox extends AutoCloseable

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:42–77

定义沙箱契约的接口。位于 io.agentscope.harness.agent.sandbox 包，实现 AutoCloseable。核心成员包括 start、stop、shutdown、close、isRunning、getState。

An active sandbox with a fully isolated workspace.

Lifecycle:

Acquire via SandboxClient#create (new) or SandboxClient#resume (existing)
Call #start() — initializes or restores the workspace
Use #exec for command execution, #persistWorkspace/#hydrateWorkspace for archive operations
Call #stop() — persists the snapshot (does NOT destroy resources)
Call #shutdown() — destroys backend resources (tmpdir, container)
Or use #close() which calls stop + shutdown in sequence

The distinction between stop() and shutdown() is critical:

stop(): persist snapshot only — safe for both self-managed and user-managed sandboxes
shutdown(): destroy backend resources — only called on self-managed sandboxes

方法摘要Method Summary

方法Method	说明Description
`public void start() throws Exception`	执行启动相关操作。 Returns the start.
`public void stop() throws Exception`	执行停止相关操作。 Returns the stop.
`default public void shutdown() throws Exception` default	关闭资源并释放连接。 Releases resources and connections.
`public void close() throws Exception`	关闭连接并释放相关资源。 Releases resources and connections.
`public boolean isRunning()`	判断是否运行中。 Returns whether the running.
`public` `SandboxState getState()`	获取状态。 Returns the current serializable state of this sandbox.
`public` `ExecResult exec(RuntimeContext runtimeContext, String command, Integer timeoutSeconds) throws Exception`	执行 `exec` 方法。 Runs a shell command in the sandbox workspace.
`public InputStream persistWorkspace() throws Exception`	返回 `persistWorkspace` 结果。 Returns the persist workspace.
`public void hydrateWorkspace(InputStream archive) throws Exception`	设置该参数。 Performs the hydrate workspace operation.

方法详情Method Detail

start

public void start() throws Exception

执行启动相关操作。

Returns the start.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:44

stop

public void stop() throws Exception

执行停止相关操作。

Returns the stop.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:46

shutdown

default public void shutdown() throws Exception

default

关闭资源并释放连接。

Releases resources and connections.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:48–50

close

public void close() throws Exception

关闭连接并释放相关资源。

Releases resources and connections.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:52–53

isRunning

public boolean isRunning()

判断是否运行中。

Returns whether the running.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:55

getState

public SandboxState getState()

获取状态。

Returns the current serializable state of this sandbox.

返回Returns SandboxState

返回SandboxState。state (may be modified by lifecycle methods)

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:62

exec

public ExecResult exec(RuntimeContext runtimeContext, String command, Integer timeoutSeconds) throws Exception

执行 exec 方法。

Runs a shell command in the sandbox workspace.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent context (session, user, attributes); may be `null`
`command`	String	命令（类型 `String`）。shell command
`timeoutSeconds`	Integer	超时秒（类型 `Integer`）。max wait; `null` for implementation default

返回Returns ExecResult

返回ExecResult。Returns exec result.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:71–72

persistWorkspace

public InputStream persistWorkspace() throws Exception

返回 persistWorkspace 结果。

Returns the persist workspace.

返回Returns InputStream

返回InputStream。Returns input stream.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:74

hydrateWorkspace

public void hydrateWorkspace(InputStream archive) throws Exception

设置该参数。

Performs the hydrate workspace operation.

参数Parameters

名称Name	类型Type	说明Description
`archive`	InputStream	归档（类型 `InputStream`）。The archive.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/Sandbox.java:76