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

WorkerEnvironmentController

@RestController @RequestMapping("/api/environments/{id}") public class WorkerEnvironmentController

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:50–227

工作进程环境控制器，承载智能体的部署、调度与服务化运行。位于 io.agentscope.builder.web.api 包。核心成员包括 poll、listWork、workStats、getWork、ack、heartbeat。

REST surface for out-of-process Environment Workers on self_hosted environments. Workers long-poll #poll, acknowledge with #ack, heartbeat, and #stop. Tool execution is event-driven (pending tools + tool-results) — see SelfHostedWorkerController.

Worker ops authenticate via X-Builder-Environment-Key; list/stats/get require a user JWT.

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`AckRequest`	记录record	用于确认:可选工作进程标识和工作区目录的请求正文。 Request body for ack: optional worker id and workspace directory.
`UpdateWorkRequest`	记录record	承载更新 Work 请求数据的记录类型。 Request body for optional work-item metadata update.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `WorkerEnvironmentController(EnvironmentWorkQueue workQueue, DataSessionService sessionService)`	初始化 `WorkerEnvironmentController` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public Mono<ResponseEntity<EnvironmentWorkQueue.WorkItem>> poll(String environmentId, String workerId, long timeoutMs)`	执行 `poll` 方法。 Long-poll for the next work item.
`public Mono<List<EnvironmentWorkQueue.WorkItem>> listWork(String environmentId, String state, Authentication auth)`	列出 `listWork`。 Lists work items for the environment, optionally filtered by `state`.
`public Mono<CoordinationStore.WorkStats> workStats(String environmentId, Authentication auth)`	执行 `workStats` 方法。 Returns per-status counts and oldest queued age for the environment.
`public Mono<EnvironmentWorkQueue.WorkItem> getWork(String environmentId, String workId, Authentication auth)`	获取 `getWork`。 Returns a single work item by id.
`public Mono<Void> ack(String environmentId, String workId,` `AckRequest req)`	执行确认相关操作。 Acknowledges a polled work item and marks the row active.
`public Mono<Void> heartbeat(String environmentId, String workId)`	执行心跳相关操作。 Bumps `updated_at` on an active work item (lease heartbeat).
`public Mono<Void> stop(String environmentId, String workId)`	执行停止相关操作。 Marks a work item stopped once the session turn has released the sandbox.
`public Mono<Void> updateWork(String environmentId, String workId,` `UpdateWorkRequest req)`	更新 `updateWork`。 Optional metadata update on an existing work item.

构造器详情Constructor Detail

WorkerEnvironmentController

public WorkerEnvironmentController(EnvironmentWorkQueue workQueue, DataSessionService sessionService)

初始化 WorkerEnvironmentController 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`workQueue`	EnvironmentWorkQueue	work 队列（类型 `EnvironmentWorkQueue`）。The work queue.
`sessionService`	DataSessionService	会话服务（类型 `DataSessionService`）。The session service.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:57–61

方法详情Method Detail

poll

public Mono<ResponseEntity<EnvironmentWorkQueue.WorkItem>> poll(String environmentId, String workerId, long timeoutMs)

执行 poll 方法。

Long-poll for the next work item.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`workerId`	String	工作进程标识（类型 `String`）。The worker id.
`timeoutMs`	long	超时 Ms（类型 `long`）。The timeout ms.

返回Returns Mono<ResponseEntity<EnvironmentWorkQueue.WorkItem>>

返回Mono>。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:73–92

listWork

public Mono<List<EnvironmentWorkQueue.WorkItem>> listWork(String environmentId, String state, Authentication auth)

列出 listWork。

Lists work items for the environment, optionally filtered by state.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`state`	String	状态对象（类型 `String`）。The state.
`auth`	Authentication	认证（类型 `Authentication`）。The auth.

返回Returns Mono<List<EnvironmentWorkQueue.WorkItem>>

返回Mono>。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:106–113

workStats

public Mono<CoordinationStore.WorkStats> workStats(String environmentId, Authentication auth)

执行 workStats 方法。

Returns per-status counts and oldest queued age for the environment.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`auth`	Authentication	认证（类型 `Authentication`）。The auth.

返回Returns Mono<CoordinationStore.WorkStats>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:116–121

getWork

public Mono<EnvironmentWorkQueue.WorkItem> getWork(String environmentId, String workId, Authentication auth)

获取 getWork。

Returns a single work item by id.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`workId`	String	work 标识（类型 `String`）。The work id.
`auth`	Authentication	认证（类型 `Authentication`）。The auth.

返回Returns Mono<EnvironmentWorkQueue.WorkItem>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:124–139

ack

public Mono<Void> ack(String environmentId, String workId, AckRequest req)

执行确认相关操作。

Acknowledges a polled work item and marks the row active.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`workId`	String	work 标识（类型 `String`）。The work id.
`req`	AckRequest	req（类型 `AckRequest`）。The req.

返回Returns Mono<Void>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:146–171

heartbeat

public Mono<Void> heartbeat(String environmentId, String workId)

执行心跳相关操作。

Bumps updated_at on an active work item (lease heartbeat).

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`workId`	String	work 标识（类型 `String`）。The work id.

返回Returns Mono<Void>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:174–178

stop

public Mono<Void> stop(String environmentId, String workId)

执行停止相关操作。

Marks a work item stopped once the session turn has released the sandbox.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`workId`	String	work 标识（类型 `String`）。The work id.

返回Returns Mono<Void>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:181–185

updateWork

public Mono<Void> updateWork(String environmentId, String workId, UpdateWorkRequest req)

更新 updateWork。

Optional metadata update on an existing work item.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`workId`	String	work 标识（类型 `String`）。The work id.
`req`	UpdateWorkRequest	req（类型 `UpdateWorkRequest`）。The req.

返回Returns Mono<Void>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/WorkerEnvironmentController.java:188–211

嵌套类详情Nested Class Detail

AckRequest

public record AckRequest(String workerId, String workDir)

用于确认:可选工作进程标识和工作区目录的请求正文。位于 io.agentscope.builder.web.api 包。核心成员包括 workerId、workDir。

Request body for ack: optional worker id and workspace directory.

UpdateWorkRequest

public record UpdateWorkRequest(String workerId, String workDir)

承载更新 Work 请求数据的记录类型。位于 io.agentscope.builder.web.api 包。核心成员包括 workerId、workDir。

Request body for optional work-item metadata update.