类class io.agentscope.harness.agent.sandbox 2.x

SandboxManager

public class SandboxManager

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:43–270

沙箱管理器，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.sandbox 包。核心成员包括 acquire、release、persistState、clearState、SandboxManager。

Manages the lifecycle of Sandbox instances for the current call.

Acquire priority: SandboxContext#getExternalSandbox() > SandboxContext#getExternalSandboxState() > persisted SandboxState > SandboxClient#create. When a persisted state exists but the resume fails, the fresh-create fallback keeps the persisted snapshot id so the workspace restores from the previous archive instead of silently resetting.

When a SandboxExecutionGuard is configured, the manager acquires an execution SandboxLease before sandbox resume/create for isolation keys that are present. The lease is carried by the SandboxAcquireResult and closed by the caller (io.agentscope.harness.agent.middleware.SandboxLifecycleMiddleware) after #release, ensuring the full call window is covered.

Priority 1 (external sandbox) and Priority 2 (external sandbox state) bypass the guard, since the caller is managing that sandbox externally.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `SandboxManager(SandboxClient<?> client, SessionSandboxStateStore stateStore, String agentId)`	初始化 `SandboxManager` 实例。 Creates a new instance.
`public` `SandboxManager(SandboxClient<?> client, SessionSandboxStateStore stateStore, String agentId, SandboxExecutionGuard executionGuard)`	初始化 `SandboxManager` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public` `SandboxAcquireResult acquire(SandboxContext sandboxContext, RuntimeContext runtimeContext) throws Exception`	执行 `acquire` 方法。 Performs the acquire operation.
`public void release(SandboxAcquireResult result)`	关闭资源并释放连接。 Releases resources and connections.
`public void persistState(SandboxAcquireResult result, SandboxContext sandboxContext, RuntimeContext runtimeContext)`	执行 `persistState` 方法。 Performs the persist state operation.
`public void clearState(SandboxContext sandboxContext, RuntimeContext runtimeContext)`	清空状态。 Clears the state.

构造器详情Constructor Detail

SandboxManager

public SandboxManager(SandboxClient<?> client, SessionSandboxStateStore stateStore, String agentId)

初始化 SandboxManager 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`client`	SandboxClient<?>	客户端（类型 `SandboxClient`）。The client.
`stateStore`	SessionSandboxStateStore	状态存储（类型 `SessionSandboxStateStore`）。The state store.
`agentId`	String	智能体标识（类型 `String`）。The agent id.

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:52–55

SandboxManager

public SandboxManager(SandboxClient<?> client, SessionSandboxStateStore stateStore, String agentId, SandboxExecutionGuard executionGuard)

初始化 SandboxManager 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`client`	SandboxClient<?>	客户端（类型 `SandboxClient`）。The client.
`stateStore`	SessionSandboxStateStore	状态存储（类型 `SessionSandboxStateStore`）。The state store.
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`executionGuard`	SandboxExecutionGuard	执行守卫（类型 `SandboxExecutionGuard`）。The execution guard.

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:57–67

方法详情Method Detail

acquire

public SandboxAcquireResult acquire(SandboxContext sandboxContext, RuntimeContext runtimeContext) throws Exception

执行 acquire 方法。

Performs the acquire operation.

参数Parameters

名称Name	类型Type	说明Description
`sandboxContext`	SandboxContext	沙箱上下文（类型 `SandboxContext`）。The sandbox context.
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.

返回Returns SandboxAcquireResult

返回SandboxAcquireResult。Returns sandbox acquire result.

抛出Throws

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

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:69–155

release

public void release(SandboxAcquireResult result)

关闭资源并释放连接。

Releases resources and connections.

参数Parameters

名称Name	类型Type	说明Description
`result`	SandboxAcquireResult	结果（类型 `SandboxAcquireResult`）。The result.

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:184–212

persistState

public void persistState(SandboxAcquireResult result, SandboxContext sandboxContext, RuntimeContext runtimeContext)

执行 persistState 方法。

Performs the persist state operation.

参数Parameters

名称Name	类型Type	说明Description
`result`	SandboxAcquireResult	结果（类型 `SandboxAcquireResult`）。The result.
`sandboxContext`	SandboxContext	沙箱上下文（类型 `SandboxContext`）。The sandbox context.
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:214–252

clearState

public void clearState(SandboxContext sandboxContext, RuntimeContext runtimeContext)

清空状态。

Clears the state.

参数Parameters

名称Name	类型Type	说明Description
`sandboxContext`	SandboxContext	沙箱上下文（类型 `SandboxContext`）。The sandbox context.
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.

源码Source io/agentscope/harness/agent/sandbox/SandboxManager.java:254–269