类class io.agentscope.builder.control 2.x

ControlPlaneClient

@Service public class ControlPlaneClient

源码Source io/agentscope/builder/control/ControlPlaneClient.java:48–604

控制面客户端，封装与远端服务的连接和调用。位于 io.agentscope.builder.control 包。核心成员包括 collaborationMcpUrl、appendSessionEvent、heartbeatManagedExecution、resolveSession、beginManagedExecution、endManagedExecution。

Data-plane HTTP client for control-plane (aistiod) internal APIs. Session and environment metadata live in the CP schema; the data plane must not SELECT those tables directly.

Authenticates with X-Builder-Internal-Token; optional X-Builder-Internal-User attributes the call to an acting owner. Methods currently block() for simplicity — callers on WebFlux handlers must schedule onto Schedulers.boundedElastic() (see DataSessionApiController).

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`ManagedExecutionScope`	记录record	承载托管执行范围数据的记录类型。 Immutable fence attached to all events emitted by one admitted Managed AgentTask turn.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `ControlPlaneClient(String controlPlaneUrl, String internalToken, ObjectMapper objectMapper)`	初始化 `ControlPlaneClient` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public String collaborationMcpUrl()`	返回 `collaborationMcpUrl` 结果。 Absolute URL of the task-scoped collaboration MCP endpoint.
`public void appendSessionEvent(SessionEventDto event)`	追加会话事件。 Mirrors one durable managed event into the control-plane session read model.
`public void appendSessionEvent(SessionEventDto event, ManagedExecutionScope scope)`	追加会话事件。 Mirrors one event with an explicit immutable fence, including from a different replica.
`public void heartbeatManagedExecution(String sessionId)`	设置心跳托管执行。 Renews the current managed AgentTask attempt while its model turn is active.
`public void heartbeatManagedExecution(String sessionId,` `ManagedExecutionScope scope)`	执行心跳托管执行相关操作。 Heartbeats one captured turn without accidentally adopting a newer session scope.
`public` `SessionResolveResult resolveSession(String sessionId)`	解析会话。 Resolves a session plus agent snapshot, environment, vault credentials and memory mounts in one round-trip.
`public` `SessionResolveResult resolveSession(String sessionId, String actingUserId)`	解析会话。 Resolves a session, optionally attributing the call to `actingUserId`.
`public` `ManagedExecutionScope beginManagedExecution(String sessionId)`	设置该参数。 Captures the Attempt fence for one admitted physical turn.
`public void endManagedExecution(String sessionId)`	设置结束托管执行。 Releases the immutable Attempt fence captured for a completed physical turn.
`public void endManagedExecution(String sessionId,` `ManagedExecutionScope expectedScope)`	执行结束托管执行相关操作。 Releases this turn's scope without deleting a newer turn that reused the same session.
`public` `ManagedExecutionScope managedExecutionScope(String sessionId)`	设置托管执行范围。 Returns the immutable AgentTask execution fence captured for the active physical turn.
`public List<SessionListItem> listSessions()`	列出会话。 Lists recent product sessions for data-plane contract probing (`GET /agentscope/sessions`).
`public List<SessionListItem> listSessions(int limit)`	列出会话。 Lists recent product sessions, capped at `limit` (server may clamp further).
`public long registerDataPlane(Map<String, Object> body)`	注册数据面。 Registers this data-plane instance with aistiod (`POST /api/v1/dataplanes/register`).
`public void heartbeatDataPlane(String instanceId)`	设置心跳数据面。 Heartbeats a registered instance (`POST /api/v1/dataplanes/{id}/heartbeat`).
`public void deleteDataPlane(String instanceId)`	删除数据面。 Unregisters a data-plane instance (`DELETE /api/v1/dataplanes/{id}`).
`public void patchSessionRuntime(String sessionId, String status, Map<String, Object> stopReason)`	执行 `patchSessionRuntime` 方法。 Patches runtime fields (`status`, `stopReason`) on a session.
`public void patchSessionRuntime(String sessionId, String status, Map<String, Object> stopReason, String actingUserId)`	执行 `patchSessionRuntime` 方法。 Patches session runtime status, optionally attributing the call to `actingUserId`.
`public void patchSessionRuntime(String sessionId, String status, Map<String, Object> stopReason, String actingUserId,` `ManagedExecutionScope scope)`	执行 `patchSessionRuntime` 方法。 Patches runtime status with the immutable fence captured when this physical turn was admitted.
`public` `EnvironmentDto getEnvironment(String environmentId)`	获取环境。 Loads an environment template by id from the control plane.
`public` `EnvironmentDto getEnvironment(String environmentId, String actingUserId)`	获取环境。 Loads an environment template, optionally attributing the call to `actingUserId`.
`public boolean verifyEnvironmentKey(String environmentId, String plaintextKey)`	执行 `verifyEnvironmentKey` 方法。 Verifies an Environment Worker API key via the control plane.
`public` `io.agentscope.builder.web.managed.MemoryDocumentStore memoryDocuments(String sessionId, String storeId)`	执行记忆文档相关操作。 Memory calls remain session-scoped; CP rechecks mount ownership and access on each request.

构造器详情Constructor Detail

ControlPlaneClient

public ControlPlaneClient(String controlPlaneUrl, String internalToken, ObjectMapper objectMapper)

初始化 ControlPlaneClient 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`controlPlaneUrl`	String	控制面 URL（类型 `String`）。The control plane url.
`internalToken`	String	内部令牌（类型 `String`）。The internal token.
`objectMapper`	ObjectMapper	对象 Mapper（类型 `ObjectMapper`）。The object mapper.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:60–71

方法详情Method Detail

collaborationMcpUrl

public String collaborationMcpUrl()

返回 collaborationMcpUrl 结果。

Absolute URL of the task-scoped collaboration MCP endpoint.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:74–76

appendSessionEvent

public void appendSessionEvent(SessionEventDto event)

追加会话事件。

Mirrors one durable managed event into the control-plane session read model.

参数Parameters

名称Name	类型Type	说明Description
`event`	SessionEventDto	事件（类型 `SessionEventDto`）。The event.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:79–81

appendSessionEvent

public void appendSessionEvent(SessionEventDto event, ManagedExecutionScope scope)

追加会话事件。

Mirrors one event with an explicit immutable fence, including from a different replica.

参数Parameters

名称Name	类型Type	说明Description
`event`	SessionEventDto	事件（类型 `SessionEventDto`）。The event.
`scope`	ManagedExecutionScope	范围（类型 `ManagedExecutionScope`）。The scope.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:84–104

heartbeatManagedExecution

public void heartbeatManagedExecution(String sessionId)

设置心跳托管执行。

Renews the current managed AgentTask attempt while its model turn is active.

参数Parameters

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

源码Source io/agentscope/builder/control/ControlPlaneClient.java:107–113

heartbeatManagedExecution

public void heartbeatManagedExecution(String sessionId, ManagedExecutionScope scope)

执行心跳托管执行相关操作。

Heartbeats one captured turn without accidentally adopting a newer session scope.

参数Parameters

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

源码Source io/agentscope/builder/control/ControlPlaneClient.java:116–136

resolveSession

public SessionResolveResult resolveSession(String sessionId)

解析会话。

Resolves a session plus agent snapshot, environment, vault credentials and memory mounts in one round-trip.

参数Parameters

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

返回Returns SessionResolveResult

返回SessionResolveResult。Returns session resolve result.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:142–144

resolveSession

public SessionResolveResult resolveSession(String sessionId, String actingUserId)

解析会话。

Resolves a session, optionally attributing the call to actingUserId.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`actingUserId`	String	执行用户标识（类型 `String`）。The acting user id.

返回Returns SessionResolveResult

返回SessionResolveResult。Returns session resolve result.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:147–180

beginManagedExecution

public ManagedExecutionScope beginManagedExecution(String sessionId)

设置该参数。

Captures the Attempt fence for one admitted physical turn.

参数Parameters

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

返回Returns ManagedExecutionScope

返回ManagedExecutionScope。Returns managed execution scope.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:187–196

endManagedExecution

public void endManagedExecution(String sessionId)

设置结束托管执行。

Releases the immutable Attempt fence captured for a completed physical turn.

参数Parameters

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

源码Source io/agentscope/builder/control/ControlPlaneClient.java:199–201

endManagedExecution

public void endManagedExecution(String sessionId, ManagedExecutionScope expectedScope)

执行结束托管执行相关操作。

Releases this turn's scope without deleting a newer turn that reused the same session.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`expectedScope`	ManagedExecutionScope	expected 范围（类型 `ManagedExecutionScope`）。The expected scope.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:204–208

managedExecutionScope

public ManagedExecutionScope managedExecutionScope(String sessionId)

设置托管执行范围。

Returns the immutable AgentTask execution fence captured for the active physical turn.

参数Parameters

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

返回Returns ManagedExecutionScope

返回ManagedExecutionScope。Returns managed execution scope.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:211–213

listSessions

public List<SessionListItem> listSessions()

列出会话。

Lists recent product sessions for data-plane contract probing (GET /agentscope/sessions).

返回Returns List<SessionListItem>

返回列出。Returns list.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:259–261

listSessions

public List<SessionListItem> listSessions(int limit)

列出会话。

Lists recent product sessions, capped at limit (server may clamp further).

参数Parameters

名称Name	类型Type	说明Description
`limit`	int	数量上限（类型 `int`）。preferred upper bound

返回Returns List<SessionListItem>

返回列出。sessions newest-first; empty when the CP returns none

源码Source io/agentscope/builder/control/ControlPlaneClient.java:269–310

registerDataPlane

public long registerDataPlane(Map<String, Object> body)

注册数据面。

Registers this data-plane instance with aistiod (POST /api/v1/dataplanes/register).

参数Parameters

名称Name	类型Type	说明Description
`body`	Map<String, Object>	正文（类型 `Map`）。The body.

返回Returns long

返回数值结果。heartbeat interval seconds from the response, or 15 when absent

源码Source io/agentscope/builder/control/ControlPlaneClient.java:317–342

heartbeatDataPlane

public void heartbeatDataPlane(String instanceId)

设置心跳数据面。

Heartbeats a registered instance (POST /api/v1/dataplanes/{id}/heartbeat).

参数Parameters

名称Name	类型Type	说明Description
`instanceId`	String	实例标识（类型 `String`）。The instance id.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:345–363

deleteDataPlane

public void deleteDataPlane(String instanceId)

删除数据面。

Unregisters a data-plane instance (DELETE /api/v1/dataplanes/{id}).

参数Parameters

名称Name	类型Type	说明Description
`instanceId`	String	实例标识（类型 `String`）。The instance id.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:366–383

patchSessionRuntime

public void patchSessionRuntime(String sessionId, String status, Map<String, Object> stopReason)

执行 patchSessionRuntime 方法。

Patches runtime fields (status, stopReason) on a session.

参数Parameters

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

源码Source io/agentscope/builder/control/ControlPlaneClient.java:389–392

patchSessionRuntime

public void patchSessionRuntime(String sessionId, String status, Map<String, Object> stopReason, String actingUserId)

执行 patchSessionRuntime 方法。

Patches session runtime status, optionally attributing the call to actingUserId.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`status`	String	状态（类型 `String`）。The status.
`stopReason`	Map<String, Object>	停止推理（类型 `Map`）。The stop reason.
`actingUserId`	String	执行用户标识（类型 `String`）。The acting user id.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:395–398

patchSessionRuntime

public void patchSessionRuntime(String sessionId, String status, Map<String, Object> stopReason, String actingUserId, ManagedExecutionScope scope)

执行 patchSessionRuntime 方法。

Patches runtime status with the immutable fence captured when this physical turn was admitted.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`status`	String	状态（类型 `String`）。The status.
`stopReason`	Map<String, Object>	停止推理（类型 `Map`）。The stop reason.
`actingUserId`	String	执行用户标识（类型 `String`）。The acting user id.
`scope`	ManagedExecutionScope	范围（类型 `ManagedExecutionScope`）。The scope.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:404–449

getEnvironment

public EnvironmentDto getEnvironment(String environmentId)

获取环境。

Loads an environment template by id from the control plane.

参数Parameters

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

返回Returns EnvironmentDto

返回EnvironmentDto。Returns environment dto.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:452–454

getEnvironment

public EnvironmentDto getEnvironment(String environmentId, String actingUserId)

获取环境。

Loads an environment template, optionally attributing the call to actingUserId.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`actingUserId`	String	执行用户标识（类型 `String`）。The acting user id.

返回Returns EnvironmentDto

返回EnvironmentDto。Returns environment dto.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:457–490

verifyEnvironmentKey

public boolean verifyEnvironmentKey(String environmentId, String plaintextKey)

执行 verifyEnvironmentKey 方法。

Verifies an Environment Worker API key via the control plane.

参数Parameters

名称Name	类型Type	说明Description
`environmentId`	String	环境标识（类型 `String`）。The environment id.
`plaintextKey`	String	plaintext 键（类型 `String`）。The plaintext key.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:496–514

memoryDocuments

public io.agentscope.builder.web.managed.MemoryDocumentStore memoryDocuments(String sessionId, String storeId)

执行记忆文档相关操作。

Memory calls remain session-scoped; CP rechecks mount ownership and access on each request.

参数Parameters

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

返回Returns io.agentscope.builder.web.managed.MemoryDocumentStore

返回io.agentscope.构建器.Web.托管.MemoryDocumentStore。Returns io agentscope builder web managed memory document store.

源码Source io/agentscope/builder/control/ControlPlaneClient.java:517–583

嵌套类详情Nested Class Detail

ManagedExecutionScope

public record ManagedExecutionScope( String tenant, String agentTaskId, String attemptId, long dispatchGeneration, String turnId)

承载托管执行范围数据的记录类型。位于 io.agentscope.builder.control 包。核心成员包括 tenant、agentTaskId、attemptId、dispatchGeneration、turnId。

Immutable fence attached to all events emitted by one admitted Managed AgentTask turn.