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

DataSessionService

@Service public class DataSessionService

源码Source io/agentscope/builder/web/managed/DataSessionService.java:39–210

数据会话服务，承载智能体的部署、调度与服务化运行。位于 io.agentscope.builder.web.managed 包。核心成员包括 get、requireById、updateStatus、mergeAgentOverrides、runTurn、resolve。

Data-plane session service: status transitions, override merges and turn execution for sessions that were created (and version-pinned) by the control plane.

Session rows live in the control-plane schema. This service reads and patches them via ControlPlaneClient and keeps the local SessionEventLog for transcript / SSE fan-out.

字段摘要Field Summary

字段Field	类型Type	说明Description
`STATUS_CREATED` staticfinaldeprecated	String	状态已创建字段。 @deprecated use {@link SessionStatuses#CREATED}
`STATUS_RUNNING` staticfinaldeprecated	String	状态运行中字段。 @deprecated use {@link SessionStatuses#RUNNING}
`STATUS_IDLE` staticfinaldeprecated	String	状态 IDLE字段。 @deprecated use {@link SessionStatuses#IDLE}
`STATUS_REQUIRES_ACTION` staticfinaldeprecated	String	状态 REQUIRES 动作字段。 @deprecated use {@link SessionStatuses#REQUIRES_ACTION}
`STATUS_TERMINATED` staticfinaldeprecated	String	状态 TERMINATED字段。 @deprecated use {@link SessionStatuses#TERMINATED}
`STATUS_RESCHEDULED` staticfinaldeprecated	String	状态 RESCHEDULED字段。 @deprecated use {@link SessionStatuses#RESCHEDULED}
`STATUS_ARCHIVED` staticfinaldeprecated	String	状态 ARCHIVED字段。 @deprecated use {@link SessionStatuses#ARCHIVED}

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `DataSessionService(ControlPlaneClient controlPlaneClient, SessionEventLog eventLog, ManagedJsonHelper jsonHelper, SessionTurnRunner turnRunner)`	初始化 `DataSessionService` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public` `ManagedSessionDto get(String ownerId, String sessionId)`	按条件读取数据。 Returns a session owned by the caller.
`public` `ManagedSessionDto requireById(String sessionId)`	设置该参数。 Looks up a session by id without owner scoping (worker / internal use).
`public` `ManagedSessionDto updateStatus(String ownerId, String sessionId, String status, Map<String, Object> stopReason)`	更新状态。 Updates session status and optional stop reason metadata via the control plane.
`public` `ManagedSessionDto updateStatus(String ownerId, String sessionId, String status, Map<String, Object> stopReason, ManagedExecutionScope scope)`	更新状态。 Updates status using the immutable fence of the physical turn that produced it.
`public` `ManagedSessionDto mergeAgentOverrides(String ownerId, String sessionId, Map<String, Object> patch)`	合并 `mergeAgentOverrides`。 Merges session-scoped agent overrides.
`public void runTurn(String ownerId, String sessionId, Map<String, Object> messagePayload)`	运行轮次。 Runs one harness turn for the session asynchronously.
`public void runTurn(String ownerId, String sessionId, Map<String, Object> messagePayload, Runnable onAdmitted)`	运行轮次。 Runs one harness turn asynchronously, invoking `onAdmitted` once the turn is certain to run.
`public` `SessionResolveResult resolve(String sessionId)`	设置解析。 Resolves the full control-plane session payload (snapshot, mounts, environment).

字段详情Field Detail

STATUS_CREATED

public static final String STATUS_CREATED

staticfinaldeprecated

状态已创建字段。声明为 public static final String STATUS_CREATED。

@deprecated use {@link SessionStatuses#CREATED}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#CREATED`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:45

STATUS_RUNNING

public static final String STATUS_RUNNING

staticfinaldeprecated

状态运行中字段。声明为 public static final String STATUS_RUNNING。

@deprecated use {@link SessionStatuses#RUNNING}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#RUNNING`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:48

STATUS_IDLE

public static final String STATUS_IDLE

staticfinaldeprecated

状态 IDLE字段。声明为 public static final String STATUS_IDLE。

@deprecated use {@link SessionStatuses#IDLE}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#IDLE`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:51

STATUS_REQUIRES_ACTION

public static final String STATUS_REQUIRES_ACTION

staticfinaldeprecated

状态 REQUIRES 动作字段。声明为 public static final String STATUS_REQUIRES_ACTION。

@deprecated use {@link SessionStatuses#REQUIRES_ACTION}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#REQUIRES_ACTION`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:54

STATUS_TERMINATED

public static final String STATUS_TERMINATED

staticfinaldeprecated

状态 TERMINATED字段。声明为 public static final String STATUS_TERMINATED。

@deprecated use {@link SessionStatuses#TERMINATED}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#TERMINATED`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:57

STATUS_RESCHEDULED

public static final String STATUS_RESCHEDULED

staticfinaldeprecated

状态 RESCHEDULED字段。声明为 public static final String STATUS_RESCHEDULED。

@deprecated use {@link SessionStatuses#RESCHEDULED}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#RESCHEDULED`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:60

STATUS_ARCHIVED

public static final String STATUS_ARCHIVED

staticfinaldeprecated

状态 ARCHIVED字段。声明为 public static final String STATUS_ARCHIVED。

@deprecated use {@link SessionStatuses#ARCHIVED}

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `SessionStatuses#ARCHIVED`

源码Source io/agentscope/builder/web/managed/DataSessionService.java:63

构造器详情Constructor Detail

DataSessionService

public DataSessionService(ControlPlaneClient controlPlaneClient, SessionEventLog eventLog, ManagedJsonHelper jsonHelper, SessionTurnRunner turnRunner)

初始化 DataSessionService 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`controlPlaneClient`	ControlPlaneClient	控制面客户端（类型 `ControlPlaneClient`）。The control plane client.
`eventLog`	SessionEventLog	事件日志（类型 `SessionEventLog`）。The event log.
`jsonHelper`	ManagedJsonHelper	JSON Helper（类型 `ManagedJsonHelper`）。The json helper.
`turnRunner`	SessionTurnRunner	轮次运行器（类型 `SessionTurnRunner`）。The turn runner.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:70–79

方法详情Method Detail

get

public ManagedSessionDto get(String ownerId, String sessionId)

按条件读取数据。

Returns a session owned by the caller.

参数Parameters

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

返回Returns ManagedSessionDto

返回ManagedSessionDto。Returns managed session dto.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:82–88

requireById

public ManagedSessionDto requireById(String sessionId)

设置该参数。

Looks up a session by id without owner scoping (worker / internal use).

参数Parameters

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

返回Returns ManagedSessionDto

返回ManagedSessionDto。Returns managed session dto.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:91–93

updateStatus

public ManagedSessionDto updateStatus(String ownerId, String sessionId, String status, Map<String, Object> stopReason)

更新状态。

Updates session status and optional stop reason metadata via the control plane.

参数Parameters

名称Name	类型Type	说明Description
`ownerId`	String	所有者标识（类型 `String`）。The owner id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`status`	String	状态（类型 `String`）。The status.
`stopReason`	Map<String, Object>	停止推理（类型 `Map`）。The stop reason.

返回Returns ManagedSessionDto

返回ManagedSessionDto。Returns managed session dto.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:96–99

updateStatus

public ManagedSessionDto updateStatus(String ownerId, String sessionId, String status, Map<String, Object> stopReason, ManagedExecutionScope scope)

更新状态。

Updates status using the immutable fence of the physical turn that produced it.

参数Parameters

名称Name	类型Type	说明Description
`ownerId`	String	所有者标识（类型 `String`）。The owner id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`status`	String	状态（类型 `String`）。The status.
`stopReason`	Map<String, Object>	停止推理（类型 `Map`）。The stop reason.
`scope`	ManagedExecutionScope	范围（类型 `ManagedExecutionScope`）。The scope.

返回Returns ManagedSessionDto

返回ManagedSessionDto。Returns managed session dto.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:102–148

mergeAgentOverrides

public ManagedSessionDto mergeAgentOverrides(String ownerId, String sessionId, Map<String, Object> patch)

合并 mergeAgentOverrides。

Merges session-scoped agent overrides.

参数Parameters

名称Name	类型Type	说明Description
`ownerId`	String	所有者标识（类型 `String`）。The owner id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`patch`	Map<String, Object>	patch（类型 `Map`）。The patch.

返回Returns ManagedSessionDto

返回ManagedSessionDto。Returns managed session dto.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:155–167

runTurn

public void runTurn(String ownerId, String sessionId, Map<String, Object> messagePayload)

运行轮次。

Runs one harness turn for the session asynchronously.

参数Parameters

名称Name	类型Type	说明Description
`ownerId`	String	所有者标识（类型 `String`）。The owner id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`messagePayload`	Map<String, Object>	消息负载（类型 `Map`）。The message payload.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:170–172

runTurn

public void runTurn(String ownerId, String sessionId, Map<String, Object> messagePayload, Runnable onAdmitted)

运行轮次。

Runs one harness turn asynchronously, invoking onAdmitted once the turn is certain to run.

参数Parameters

名称Name	类型Type	说明Description
`ownerId`	String	所有者标识（类型 `String`）。The owner id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`messagePayload`	Map<String, Object>	消息负载（类型 `Map`）。The message payload.
`onAdmitted`	Runnable	on Admitted（类型 `Runnable`）。The on admitted.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:178–188

resolve

public SessionResolveResult resolve(String sessionId)

设置解析。

Resolves the full control-plane session payload (snapshot, mounts, environment).

参数Parameters

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

返回Returns SessionResolveResult

返回SessionResolveResult。Returns session resolve result.

源码Source io/agentscope/builder/web/managed/DataSessionService.java:191–193