SandboxLifecycleMiddleware
public class SandboxLifecycleMiddleware implements HarnessRuntimeMiddlewareio/agentscope/harness/agent/middleware/SandboxLifecycleMiddleware.java:56–180沙箱生命周期中间件，在智能体执行流程中提供横切扩展。位于 io.agentscope.harness.agent.middleware 包，实现 HarnessRuntimeMiddleware。核心成员包括 setBeforeStartCallback、acquireForCall、releaseForCall、SandboxLifecycleMiddleware。
Middleware that manages the sandbox session lifecycle around each agent call.
Pre-next.apply
-
Read
SandboxContextfrom the currentRuntimeContext -
Acquire a session via
SandboxManager -
Start the session (4-branch workspace init)
-
Bind the live session on the per-call
RuntimeContextfor theSandboxBackedFilesystemproxy to resolve
doFinally
-
Release the session via
SandboxManager(stop + optional shutdown) -
Persist sandbox session state via
SandboxManagerandio.agentscope.harness.agent.sandbox.SessionSandboxStateStore -
Clear this call's session binding from the
RuntimeContext
Post-call failures (persist, release) are logged but do not propagate — this ensures the agent call result is always returned to the caller even if sandbox cleanup fails.
The sandbox is bound per call on the invocation's RuntimeContext rather than
on a shared agent-level slot: distinct (userId, sessionId) sessions run in parallel on
the same agent bean, so a shared slot would let concurrent calls corrupt each other's binding
(issue #2490).
构造器摘要Constructor Summary
| 构造器Constructor | 说明Description |
|---|---|
public SandboxLifecycleMiddleware(SandboxManager sandboxManager, SandboxBackedFilesystem filesystemProxy) | 初始化 `SandboxLifecycleMiddleware` 实例。 Creates a new instance. |
方法摘要Method Summary
| 方法Method | 说明Description |
|---|---|
public void setBeforeStartCallback(Consumer<RuntimeContext> callback) | 设置之前启动回调。 Registers a callback that runs after the sandbox session is acquired but before
`io.agentscope.harness.agent.sandbox.Sandbox#start()` applies workspace projection. |
public void acquireForCall(RuntimeContext ctx) | 设置该参数。 Acquires the sandbox for the current call. |
public void releaseForCall(RuntimeContext ctx) | 设置该参数。 Releases the sandbox after the current call. |
构造器详情Constructor Detail
SandboxLifecycleMiddleware
public SandboxLifecycleMiddleware(SandboxManager sandboxManager, SandboxBackedFilesystem filesystemProxy)初始化 SandboxLifecycleMiddleware 实例。
Creates a new instance.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
sandboxManager | SandboxManager | 沙箱管理器（类型 `SandboxManager`）。The sandbox manager. |
filesystemProxy | SandboxBackedFilesystem | 文件系统代理（类型 `SandboxBackedFilesystem`）。The filesystem proxy. |
io/agentscope/harness/agent/middleware/SandboxLifecycleMiddleware.java:64–68方法详情Method Detail
setBeforeStartCallback
public void setBeforeStartCallback(Consumer<RuntimeContext> callback)设置之前启动回调。
Registers a callback that runs after the sandbox session is acquired but before io.agentscope.harness.agent.sandbox.Sandbox#start() applies workspace projection.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
callback | Consumer<RuntimeContext> | 回调函数（类型 `Consumer`）。receives the per-call `RuntimeContext`; may be `null` to clear |
io/agentscope/harness/agent/middleware/SandboxLifecycleMiddleware.java:78–80acquireForCall
public void acquireForCall(RuntimeContext ctx)设置该参数。
Acquires the sandbox for the current call.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
ctx | RuntimeContext | 运行时上下文（类型 `RuntimeContext`）。the per-call RuntimeContext (must not be null) |
io/agentscope/harness/agent/middleware/SandboxLifecycleMiddleware.java:89–143releaseForCall
public void releaseForCall(RuntimeContext ctx)设置该参数。
Releases the sandbox after the current call.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
ctx | RuntimeContext | 运行时上下文（类型 `RuntimeContext`）。the per-call RuntimeContext (captured at acquire time) |
io/agentscope/harness/agent/middleware/SandboxLifecycleMiddleware.java:151–179