类class io.agentscope.builder.web.managed 2.x

HandsLeaseService

@Service public class HandsLeaseService

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:37–161

Hands Lease 服务，承载智能体的部署、调度与服务化运行。位于 io.agentscope.builder.web.managed 包。核心成员包括 acquire、release、HandsLeaseService、DEFAULT_TIMEOUT。

Brokers hands work-queue signaling for self_hosted managed sessions.

Under the Claude-style event-driven model, Brain does not hold a live sandbox. Built-in hands tools are schema-only and suspend; an Environment Worker claims the work item, executes tools locally, and posts user.tool_result to resume the turn. This service only enqueues a work item so workers can discover the session (poll/stats/stop), and never blocks waiting for a local Sandbox registration.

字段摘要Field Summary

字段Field	类型Type	说明Description
`DEFAULT_TIMEOUT` staticfinal	Duration	默认超时字段。 Default time to wait for a worker to attach a sandbox before failing the turn.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `HandsLeaseService(EnvironmentWorkQueue workQueue, ExternalSandboxRegistry registry, HandsMetrics metrics)`	初始化 `HandsLeaseService` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public Optional<io.agentscope.harness.agent.sandbox.Sandbox> acquire(ManagedSessionDto session, EnvironmentDto environment)`	执行 `acquire` 方法。 Signals that a `self_hosted` session needs a worker.
`public Optional<io.agentscope.harness.agent.sandbox.Sandbox> acquire(ManagedSessionDto session, EnvironmentDto environment, String turnOwnerId)`	执行 `acquire` 方法。 Acquires hands resources owned by one exact physical turn.
`public Optional<io.agentscope.harness.agent.sandbox.Sandbox> acquire(ManagedSessionDto session, EnvironmentDto environment, Duration timeout)`	执行 `acquire` 方法。 Overload of `#acquire(ManagedSessionDto, EnvironmentDto)` with an explicit timeout (retained for API compatibility; the timeout is unused because Brain no longer waits for a local sandbox).
`public void release(String sessionId)`	关闭资源并释放连接。 Releases the hands lease for a session: completes the outstanding work item and removes any registry entry.
`public void release(String sessionId, String expectedTurnOwnerId)`	关闭资源并释放连接。 Releases only when the caller still owns this session's hands work item.

字段详情Field Detail

DEFAULT_TIMEOUT

public static final Duration DEFAULT_TIMEOUT

staticfinal

默认超时字段。声明为 public static final Duration DEFAULT_TIMEOUT。

Default time to wait for a worker to attach a sandbox before failing the turn.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:43

构造器详情Constructor Detail

HandsLeaseService

public HandsLeaseService(EnvironmentWorkQueue workQueue, ExternalSandboxRegistry registry, HandsMetrics metrics)

初始化 HandsLeaseService 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`workQueue`	EnvironmentWorkQueue	work 队列（类型 `EnvironmentWorkQueue`）。The work queue.
`registry`	ExternalSandboxRegistry	注册表（类型 `ExternalSandboxRegistry`）。The registry.
`metrics`	HandsMetrics	指标（类型 `HandsMetrics`）。The metrics.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:51–58

方法详情Method Detail

acquire

public Optional<io.agentscope.harness.agent.sandbox.Sandbox> acquire(ManagedSessionDto session, EnvironmentDto environment)

执行 acquire 方法。

Signals that a self_hosted session needs a worker.

参数Parameters

名称Name	类型Type	说明Description
`session`	ManagedSessionDto	会话（类型 `ManagedSessionDto`）。The session.
`environment`	EnvironmentDto	环境（类型 `EnvironmentDto`）。The environment.

返回Returns Optional<io.agentscope.harness.agent.sandbox.Sandbox>

返回可选。Returns optional.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:66–69

acquire

public Optional<io.agentscope.harness.agent.sandbox.Sandbox> acquire(ManagedSessionDto session, EnvironmentDto environment, String turnOwnerId)

执行 acquire 方法。

Acquires hands resources owned by one exact physical turn.

参数Parameters

名称Name	类型Type	说明Description
`session`	ManagedSessionDto	会话（类型 `ManagedSessionDto`）。The session.
`environment`	EnvironmentDto	环境（类型 `EnvironmentDto`）。The environment.
`turnOwnerId`	String	轮次所有者标识（类型 `String`）。The turn owner id.

返回Returns Optional<io.agentscope.harness.agent.sandbox.Sandbox>

返回可选。Returns optional.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:72–75

acquire

public Optional<io.agentscope.harness.agent.sandbox.Sandbox> acquire(ManagedSessionDto session, EnvironmentDto environment, Duration timeout)

执行 acquire 方法。

Overload of #acquire(ManagedSessionDto, EnvironmentDto) with an explicit timeout (retained for API compatibility; the timeout is unused because Brain no longer waits for a local sandbox).

参数Parameters

名称Name	类型Type	说明Description
`session`	ManagedSessionDto	会话（类型 `ManagedSessionDto`）。The session.
`environment`	EnvironmentDto	环境（类型 `EnvironmentDto`）。The environment.
`timeout`	Duration	超时时间（类型 `Duration`）。The timeout.

返回Returns Optional<io.agentscope.harness.agent.sandbox.Sandbox>

返回可选。Returns optional.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:82–85

release

public void release(String sessionId)

关闭资源并释放连接。

Releases the hands lease for a session: completes the outstanding work item and removes any registry entry.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:126–136

release

public void release(String sessionId, String expectedTurnOwnerId)

关闭资源并释放连接。

Releases only when the caller still owns this session's hands work item.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`expectedTurnOwnerId`	String	expected 轮次所有者标识（类型 `String`）。The expected turn owner id.

源码Source io/agentscope/builder/web/managed/HandsLeaseService.java:139–158