类class io.agentscope.extensions.controlplane preview

SessionBridge

public final class SessionBridge implements ContractProvider, AutoCloseable

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:68–1307

会话 Bridge，承载智能体的部署、调度与服务化运行。位于 io.agentscope.extensions.controlplane 包，实现 ContractProvider、AutoCloseable。核心成员包括 attach、getAdapter、getConfig、getRegisteredIdentity、getContractPort、start。

The reporting engine that sits between a framework adapter and the controlplane control plane.

It owns everything the adapter should not care about: sequence numbering, the Level-2 event durable event outbox, incremental context tracking, Level-1 aggregation, debounced Level-4 pushes, inventory, command dispatch from both channels, and the in-process contract server.

Bypass principle: every reporting path swallows its own failures. Nothing here may propagate into the agent's conversation path.

字段摘要Field Summary

字段Field	类型Type	说明Description
`SDK_VERSION` staticfinal	String	SDK 版本字段。 The SDK VERSION field.
`CONTRACT_LEVEL` staticfinal	int	契约级别字段。 Contract level 3: discovery, sessions, and commands.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `SessionBridge(ControlPlaneConfig config)`	初始化 `SessionBridge` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public` `SessionBridge attach(Object target, FrameworkAdapter adapter)`	执行 `attach` 方法。 Mounts `adapter` onto `target`; must be called before `#start()`.
`public` `FrameworkAdapter getAdapter()`	获取适配器。 Returns the adapter.
`public` `ControlPlaneConfig getConfig()`	获取配置。 Returns the config.
`public` `HttpSelfRegistration.RegisteredIdentity getRegisteredIdentity()`	获取已注册身份。 Returns the stable Catalog identity issued by the latest successful self-registration.
`public int getContractPort()`	获取 `getContractPort`。 Actual contract HTTP port, which matters when the configured port was 0.
`public synchronized` `SessionBridge start()` synchronized	返回启动。 Returns the start.
`public synchronized void close()` synchronized	关闭连接并释放相关资源。 Releases resources and connections.
`public Set<String> capabilities()`	返回能力。 Returns the capabilities.
`public void onCommittedEvent(String source, long nativeSeq,` `SessionEvent event)`	处理 `onCommittedEvent` 事件。 Acknowledges durable native export only after the local journal has forced the record.
`public void onEvent(SessionEvent event)`	处理事件事件。 Performs the on event operation.
`public void describeSession(String sessionId, String systemPrompt, List<ContextSnapshot.ToolInfo> tools, int maxTokens)`	执行 `describeSession` 方法。 Lets the adapter seed the tracker with data the event stream does not carry.
`public void describeSession(String sessionId, String systemPrompt, List<ContextSnapshot.ToolInfo> tools, int maxTokens, String model)`	执行 `describeSession` 方法。 Lets the adapter seed the tracker, including the model name when known.
`public void setEffectiveSystemPrompt(String sessionId, String prompt)`	设置 `setEffectiveSystemPrompt`。 Stores the last middleware-composed system prompt for a session.
`public String effectiveSystemPrompt(String sessionId)`	设置该参数。 Last effective system prompt for the session, or empty.
`public void setBusy(String sessionId, boolean busy)`	设置 `setBusy`。 Records whether a turn is in progress by driving `phase`: `active` while busy, `idle` when the turn ends.
`public void setPhase(String sessionId, String phase)`	设置阶段。 Sets operational phase explicitly (e.g.
`public void setContextUsedTokens(String sessionId, int usedTokens)`	设置 `setContextUsedTokens`。 Updates context-window occupancy used for Level-1 `contextPressure`.
`public Map<String, Object> info()`	返回信息。 Returns the info.
`public List<Map<String, Object>> sessions()`	返回会话。 Returns the sessions.
`public Map<String, Object> sessionState(String sessionId)`	设置会话状态。 Performs the session state operation.
`public Map<String, Object> context(String sessionId)`	设置上下文。 Performs the context operation.
`public Map<String, Object> messages(String sessionId, int offset, int limit)`	执行消息相关操作。 Performs the messages operation.
`public List<Map<String, Object>> subagents()`	返回 `subagents` 结果。 Returns the subagents.
`public List<Map<String, Object>> workspaces()`	返回 `workspaces` 结果。 Returns the workspaces.
`public void compress(String sessionId)`	设置压缩。 Performs the compress operation.
`public void terminate(String sessionId)`	设置该参数。 Performs the terminate operation.
`public void abort(String sessionId)`	设置中止。 Performs the abort operation.
`public Map<String, Object> tasks(String sessionId)`	设置任务。 Performs the tasks operation.
`public Map<String, Object> subagentTasks(String sessionId)`	设置子智能体任务。 Performs the subagent tasks operation.
`public void cancelSubagentTask(String sessionId, String taskId)`	执行取消子智能体任务相关操作。 Performs the cancel subagent task operation.
`public void planMode(String sessionId, byte[] body)`	执行计划模式相关操作。 Performs the plan mode operation.
`public void postMessage(String sessionId, byte[] body)`	执行后置消息相关操作。 Performs the post message operation.
`public Map<String, Object> exportTranscript(String sessionId)`	设置该参数。 Performs the export transcript operation.
`public String sessionPhase(String sessionId)`	设置会话阶段。 Performs the session phase operation.

字段详情Field Detail

SDK_VERSION

public static final String SDK_VERSION

staticfinal

SDK 版本字段。声明为 public static final String SDK_VERSION。

The SDK VERSION field.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:72

CONTRACT_LEVEL

public static final int CONTRACT_LEVEL

staticfinal

契约级别字段。声明为 public static final int CONTRACT_LEVEL。

Contract level 3: discovery, sessions, and commands.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:75

构造器详情Constructor Detail

SessionBridge

public SessionBridge(ControlPlaneConfig config)

初始化 SessionBridge 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`config`	ControlPlaneConfig	配置对象（类型 `ControlPlaneConfig`）。The config.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:128–143

方法详情Method Detail

attach

public SessionBridge attach(Object target, FrameworkAdapter adapter)

执行 attach 方法。

Mounts adapter onto target; must be called before #start().

参数Parameters

名称Name	类型Type	说明Description
`target`	Object	目标（类型 `Object`）。The target.
`adapter`	FrameworkAdapter	适配器（类型 `FrameworkAdapter`）。The adapter.

返回Returns SessionBridge

返回SessionBridge。Returns session bridge.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:148–157

getAdapter

public FrameworkAdapter getAdapter()

获取适配器。

Returns the adapter.

返回Returns FrameworkAdapter

返回FrameworkAdapter。Returns framework adapter.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:159–161

getConfig

public ControlPlaneConfig getConfig()

获取配置。

Returns the config.

返回Returns ControlPlaneConfig

返回ControlPlaneConfig。Returns control plane config.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:163–165

getRegisteredIdentity

public HttpSelfRegistration.RegisteredIdentity getRegisteredIdentity()

获取已注册身份。

Returns the stable Catalog identity issued by the latest successful self-registration.

返回Returns HttpSelfRegistration.RegisteredIdentity

返回HttpSelfRegistration.RegisteredIdentity。Returns http self registration registered identity.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:172–174

getContractPort

public int getContractPort()

获取 getContractPort。

Actual contract HTTP port, which matters when the configured port was 0.

返回Returns int

返回数值结果。Returns a numeric result.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:177–179

start

public synchronized SessionBridge start()

synchronized

返回启动。

Returns the start.

返回Returns SessionBridge

返回SessionBridge。Returns session bridge.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:183–316

close

public synchronized void close()

synchronized

关闭连接并释放相关资源。

Releases resources and connections.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:330–363

capabilities

public Set<String> capabilities()

返回能力。

Returns the capabilities.

返回Returns Set<String>

返回设置。Returns set.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:367–376

onCommittedEvent

public void onCommittedEvent(String source, long nativeSeq, SessionEvent event)

处理 onCommittedEvent 事件。

Acknowledges durable native export only after the local journal has forced the record.

参数Parameters

名称Name	类型Type	说明Description
`source`	String	来源（类型 `String`）。The source.
`nativeSeq`	long	原生 Seq（类型 `long`）。The native seq.
`event`	SessionEvent	事件（类型 `SessionEvent`）。The event.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:382–400

onEvent

public void onEvent(SessionEvent event)

处理事件事件。

Performs the on event operation.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:402–454

describeSession

public void describeSession(String sessionId, String systemPrompt, List<ContextSnapshot.ToolInfo> tools, int maxTokens)

执行 describeSession 方法。

Lets the adapter seed the tracker with data the event stream does not carry.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`systemPrompt`	String	系统提示词（类型 `String`）。The system prompt.
`tools`	List<ContextSnapshot.ToolInfo>	工具列表（类型 `List`）。The tools.
`maxTokens`	int	最大令牌数（类型 `int`）。The max tokens.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:457–463

describeSession

public void describeSession(String sessionId, String systemPrompt, List<ContextSnapshot.ToolInfo> tools, int maxTokens, String model)

执行 describeSession 方法。

Lets the adapter seed the tracker, including the model name when known.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`systemPrompt`	String	系统提示词（类型 `String`）。The system prompt.
`tools`	List<ContextSnapshot.ToolInfo>	工具列表（类型 `List`）。The tools.
`maxTokens`	int	最大令牌数（类型 `int`）。The max tokens.
`model`	String	模型实例（类型 `String`）。The model.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:466–490

setEffectiveSystemPrompt

public void setEffectiveSystemPrompt(String sessionId, String prompt)

设置 setEffectiveSystemPrompt。

Stores the last middleware-composed system prompt for a session.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:493–503

effectiveSystemPrompt

public String effectiveSystemPrompt(String sessionId)

设置该参数。

Last effective system prompt for the session, or empty.

参数Parameters

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

返回Returns String

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:506–514

setBusy

public void setBusy(String sessionId, boolean busy)

设置 setBusy。

Records whether a turn is in progress by driving phase: active while busy, idle when the turn ends.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:520–535

setPhase

public void setPhase(String sessionId, String phase)

设置阶段。

Sets operational phase explicitly (e.g.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:538–546

setContextUsedTokens

public void setContextUsedTokens(String sessionId, int usedTokens)

设置 setContextUsedTokens。

Updates context-window occupancy used for Level-1 contextPressure.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`usedTokens`	int	used 令牌数（类型 `int`）。The used tokens.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:549–559

info

public Map<String, Object> info()

返回信息。

Returns the info.

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:900–920

sessions

public List<Map<String, Object>> sessions()

返回会话。

Returns the sessions.

返回Returns List<Map<String, Object>>

返回列出>。Returns list.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:922–977

sessionState

public Map<String, Object> sessionState(String sessionId)

设置会话状态。

Performs the session state operation.

参数Parameters

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

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:979–1027

context

public Map<String, Object> context(String sessionId)

设置上下文。

Performs the context operation.

参数Parameters

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

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1029–1053

messages

public Map<String, Object> messages(String sessionId, int offset, int limit)

执行消息相关操作。

Performs the messages operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`offset`	int	偏移量（类型 `int`）。The offset.
`limit`	int	数量上限（类型 `int`）。The limit.

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1055–1066

subagents

public List<Map<String, Object>> subagents()

返回 subagents 结果。

Returns the subagents.

返回Returns List<Map<String, Object>>

返回列出>。Returns list.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1068–1080

workspaces

public List<Map<String, Object>> workspaces()

返回 workspaces 结果。

Returns the workspaces.

返回Returns List<Map<String, Object>>

返回列出>。Returns list.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1082–1094

compress

public void compress(String sessionId)

设置压缩。

Performs the compress operation.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1096–1110

terminate

public void terminate(String sessionId)

设置该参数。

Performs the terminate operation.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1112–1116

abort

public void abort(String sessionId)

设置中止。

Performs the abort operation.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1118–1122

tasks

public Map<String, Object> tasks(String sessionId)

设置任务。

Performs the tasks operation.

参数Parameters

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

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1124–1146

subagentTasks

public Map<String, Object> subagentTasks(String sessionId)

设置子智能体任务。

Performs the subagent tasks operation.

参数Parameters

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

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1148–1158

cancelSubagentTask

public void cancelSubagentTask(String sessionId, String taskId)

执行取消子智能体任务相关操作。

Performs the cancel subagent task operation.

参数Parameters

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1160–1166

planMode

public void planMode(String sessionId, byte[] body)

执行计划模式相关操作。

Performs the plan mode operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`body`	byte[]	正文（类型 `byte[]`）。The body.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1168–1174

postMessage

public void postMessage(String sessionId, byte[] body)

执行后置消息相关操作。

Performs the post message operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`body`	byte[]	正文（类型 `byte[]`）。The body.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1176–1190

exportTranscript

public Map<String, Object> exportTranscript(String sessionId)

设置该参数。

Performs the export transcript operation.

参数Parameters

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

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1208–1216

sessionPhase

public String sessionPhase(String sessionId)

设置会话阶段。

Performs the session phase operation.

参数Parameters

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

返回Returns String

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

源码Source io/agentscope/extensions/controlplane/SessionBridge.java:1218–1221