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

DataSessionApiController

@RestController @RequestMapping("/api/sessions") public class DataSessionApiController

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:69–406

数据会话 API 控制器，承载智能体的部署、调度与服务化运行。位于 io.agentscope.builder.web.api 包。核心成员包括 postEvents、listEvents、deleteEvents、handsStats、streamEvents、DataSessionApiController。

Data-plane session API: inbound user events (message / interrupt / tool confirmation / tool results), the persisted event log, SSE streaming and hands metrics.

Session lifecycle (create / list / get / archive / delete) is owned by the control plane under the same /api/sessions path prefix; the gateway routes those calls there.

Authorization is session ownership via DataSessionService#get: the control plane resolve payload's ownerId must match the JWT user. Product agents now live in aistiod's schema, so a dataplane JPA AgentAccessGuard lookup would 404 even for valid sessions; agent RUN/EDIT was already enforced when the session was created.

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`PostEventsRequest`	记录record	承载后置事件请求数据的记录类型。 Batch inbound event envelope.
`InboundEvent`	记录record	承载入站事件数据的记录类型。 Single inbound event with type and free-form payload fields.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `DataSessionApiController(DataSessionService sessionService, SessionEventLog eventLog, SessionEventPreviewBus previewBus, ToolConfirmationCoordinator confirmationCoordinator, SessionTurnRunner turnRunner, ObjectMapper objectMapper, HandsMetrics handsMetrics)`	初始化 `DataSessionApiController` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public Mono<List<SessionEventDto>> postEvents(String id, PostEventsRequest body, Authentication auth)`	执行后置事件相关操作。 Posts inbound user events (message, interrupt, tool confirmation).
`public Mono<List<SessionEventDto>> listEvents(String id, Long after, List<String> types, Authentication auth)`	列出事件。 Lists persisted session events, optionally after a sequence cursor and/or filtered by ` types` (repeatable query param, Claude Managed Agents `types[]` equivalent).
`public Mono<Void> deleteEvents(String id, Authentication auth)`	删除事件。 Deletes all persisted events for a session.
`public Mono<HandsMetrics.Snapshot> handsStats(String id, Authentication auth)`	执行 `handsStats` 方法。 Returns hands (sandbox lease) acquire/release/timeout counters for this session.
`public Flux<ServerSentEvent<String>> streamEvents(String id, Long after, List<String> eventDeltas, Long lastEventId, Authentication auth)`	执行事件。 Streams session events over SSE, optionally merging stream-only preview deltas.

构造器详情Constructor Detail

DataSessionApiController

public DataSessionApiController(DataSessionService sessionService, SessionEventLog eventLog, SessionEventPreviewBus previewBus, ToolConfirmationCoordinator confirmationCoordinator, SessionTurnRunner turnRunner, ObjectMapper objectMapper, HandsMetrics handsMetrics)

初始化 DataSessionApiController 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`sessionService`	DataSessionService	会话服务（类型 `DataSessionService`）。The session service.
`eventLog`	SessionEventLog	事件日志（类型 `SessionEventLog`）。The event log.
`previewBus`	SessionEventPreviewBus	预览总线（类型 `SessionEventPreviewBus`）。The preview bus.
`confirmationCoordinator`	ToolConfirmationCoordinator	确认 Coordinator（类型 `ToolConfirmationCoordinator`）。The confirmation coordinator.
`turnRunner`	SessionTurnRunner	轮次运行器（类型 `SessionTurnRunner`）。The turn runner.
`objectMapper`	ObjectMapper	对象 Mapper（类型 `ObjectMapper`）。The object mapper.
`handsMetrics`	HandsMetrics	hands 指标（类型 `HandsMetrics`）。The hands metrics.

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:84–99

方法详情Method Detail

postEvents

public Mono<List<SessionEventDto>> postEvents(String id, PostEventsRequest body, Authentication auth)

执行后置事件相关操作。

Posts inbound user events (message, interrupt, tool confirmation).

参数Parameters

名称Name	类型Type	说明Description
`id`	String	标识（类型 `String`）。The id.
`body`	PostEventsRequest	正文（类型 `PostEventsRequest`）。The body.
`auth`	Authentication	认证（类型 `Authentication`）。The auth.

返回Returns Mono<List<SessionEventDto>>

返回Mono>。Returns mono.

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:102–122

listEvents

public Mono<List<SessionEventDto>> listEvents(String id, Long after, List<String> types, Authentication auth)

列出事件。

Lists persisted session events, optionally after a sequence cursor and/or filtered by types (repeatable query param, Claude Managed Agents types[] equivalent).

参数Parameters

名称Name	类型Type	说明Description
`id`	String	标识（类型 `String`）。The id.
`after`	Long	之后（类型 `Long`）。The after.
`types`	List<String>	类型（类型 `List`）。The types.
`auth`	Authentication	认证（类型 `Authentication`）。The auth.

返回Returns Mono<List<SessionEventDto>>

返回Mono>。Returns mono.

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:128–144

deleteEvents

public Mono<Void> deleteEvents(String id, Authentication auth)

删除事件。

Deletes all persisted events for a session.

参数Parameters

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

返回Returns Mono<Void>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:155–177

handsStats

public Mono<HandsMetrics.Snapshot> handsStats(String id, Authentication auth)

执行 handsStats 方法。

Returns hands (sandbox lease) acquire/release/timeout counters for this session.

参数Parameters

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

返回Returns Mono<HandsMetrics.Snapshot>

返回Mono。Returns mono.

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:180–190

streamEvents

public Flux<ServerSentEvent<String>> streamEvents(String id, Long after, List<String> eventDeltas, Long lastEventId, Authentication auth)

执行事件。

Streams session events over SSE, optionally merging stream-only preview deltas.

参数Parameters

名称Name	类型Type	说明Description
`id`	String	标识（类型 `String`）。The id.
`after`	Long	之后（类型 `Long`）。The after.
`eventDeltas`	List<String>	事件 Deltas（类型 `List`）。The event deltas.
`lastEventId`	Long	最后事件标识（类型 `Long`）。The last event id.
`auth`	Authentication	认证（类型 `Authentication`）。The auth.

返回Returns Flux<ServerSentEvent<String>>

返回Flux>。Returns flux.

源码Source io/agentscope/builder/web/api/DataSessionApiController.java:200–258

嵌套类详情Nested Class Detail

PostEventsRequest

public record PostEventsRequest(List<InboundEvent> events)

承载后置事件请求数据的记录类型。位于 io.agentscope.builder.web.api 包。核心成员包括 events。

Batch inbound event envelope.

InboundEvent

public record InboundEvent(String type, Map<String, Object> payload)

承载入站事件数据的记录类型。位于 io.agentscope.builder.web.api 包。核心成员包括 type、payload、InboundEvent。

Single inbound event with type and free-form payload fields.