agent-core-java 会话状态机制详解:com.openjiuwen.core.session.state 包中的状态分区、提交回滚与快照恢复

原创2026-10-14 15:00:451,449 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

agent-core-java 会话状态机制详解:com.openjiuwen.core.session.state 包中的状态分区、提交回滚与快照恢复

本篇围绕 com.openjiuwen.core.session.state 包展开,系统讲解 openJiuwen agent core Java(agent-core-java)中 session 状态管理的核心抽象:状态如何按 io/global/comp/workflow 分区组织、State/StateLike/CommitStateLike 接口体系如何划分只读、可写、可恢复与可提交四类能力、InMemoryState 工厂如何快速构造工作流状态,以及节点级状态分区如何配合 checkpointer 实现中断恢复。读完本文,你可以直接读懂源码中的状态读取、更新、commit/rollback 调用链,并在自定义 Session 扩展或调试工作流状态时正确选用这些类型。

一、状态包定位:session 状态管理的核心抽象

com.openjiuwen.core.session.state 包定义了状态读取、更新、快照恢复、提交回滚以及工作流节点级状态分区的核心抽象,源码位于 core/src/main/java/com/openjiuwen/core/session/state/。该包共 11 个类型,官方 API 文档总览见 state.README.md,各类型的独立文档位于 session/state 目录。

包内类型一览(继承自 state.README.md 的类型表):

类型 说明
AgentStateCollection 管理 agent 级状态与全局状态分区。
CommitStateLike 为状态对象补充提交、回滚与待提交更新访问能力。
InMemoryCommitState 带待提交缓冲区的内存状态实现。
InMemoryState 创建内存版 WorkflowCommitState 的工厂。
InMemoryStateLike StateLike 的内存实现。
ReadableState 只读状态接口。
RecoverableState 支持快照导出与恢复的状态接口。
State session 状态管理的顶层接口。
StateLike 可读写的状态接口。
WorkflowCommitState 带提交/回滚能力的工作流状态集合。
WorkflowStateCollection 管理 io/global/comp/workflow 多分区状态的工作流状态集合。

从源码的 Javadoc 注释可以看到(如 State.java 中的 Mirrors Python's State in openjiuwen/core/session/state/base.py),Java 版的状态体系与 Python 版 openjiuwen 的状态实现一一对应,便于两种语言版本的概念互查。

二、接口体系:从只读到可提交的四级能力划分

状态包的核心设计是把"状态"按能力切成四个可组合的接口,源码分别为 ReadableState.java、RecoverableState.java、StateLike.java、CommitStateLike.java:

public interface ReadableState {
    Object get(Object key);
    Object getByPrefix(Object key, String nestedPrefix);
}

public interface RecoverableState {
    Map<String, Object> getState();
    void setState(Map<String, Object> state);
}

public interface StateLike extends ReadableState, RecoverableState {
    void update(Map<String, Object> data);
    Object getByTransformer(Function<Object, Object> transformer);
}

public interface CommitStateLike extends StateLike {
    void updateById(String nodeId, Map<String, Object> data);
    void commit(String nodeId);
    default void commit() { commit(null); }
    void rollback(String nodeId);
    Map<String, Object> getUpdates();
    void setUpdates(Map<String, Object> updates);
}

各接口承担的职责:

  • ReadableState:只读能力。get(key) 按键读取;getByPrefix(key, nestedPrefix) 在给定前缀下读取嵌套状态——这是节点间读取输入输出的关键入口,因为工作流状态把"节点输出"以 nodeId 为前缀存放在 IO 分区中;
  • RecoverableState:快照能力。getState() 导出当前状态映射、setState(state) 从快照恢复,二者共同支撑 checkpointer 的持久化与恢复流程;
  • StateLike:可读写能力。update(data) 合并一组状态更新;getByTransformer(transformer) 允许调用方传入转换函数直接从状态对象中提取派生数据,避免把整个 Map 复制出来;
  • CommitStateLike:在 StateLike 之上引入事务语义。updateById(nodeId, data) 把更新先记入待提交缓冲区而不是直接落盘;commit(nodeId) 提交指定节点(nodeId = null 时实现可以提交全部节点的待提交更新);rollback(nodeId) 丢弃指定节点的待提交更新;getUpdates()/setUpdates(updates) 用于导出/恢复待提交缓冲区,使"事务中间态"也可以被快照化。

顶层接口 State 则面向 Session 场景,把上述能力与分区键组合起来:

public interface State extends RecoverableState, SessionStateAccess {
    String IO_STATE_KEY = "io_state";
    String IO_STATE_UPDATES_KEY = "io_state_updates";
    String GLOBAL_STATE_KEY = "global_state";
    String GLOBAL_STATE_UPDATES_KEY = "global_state_updates";
    String COMP_STATE_KEY = "comp_state";
    String WORKFLOW_STATE_KEY = "workflow_state";
    String AGENT_STATE_KEY = "agent_state";
    String COMP_STATE_UPDATES_KEY = "comp_state_updates";
    String WORKFLOW_STATE_UPDATES_KEY = "workflow_state_updates";
    String DEFAULT_NODE_ID = "default";
    String DEFAULT_WORKFLOW_ID = "workflow";

    Object getGlobal(Object key);
    void updateGlobal(Map<String, Object> data);
    void updateTrace(Object span);
    void update(Map<String, Object> data);
    Object get(Object key);
    Map<String, Object> getState();
    void setState(Map<String, Object> state);
    Map<String, Object> dump();
}

从 State.java 可以看到,State 定义了两类常量:

  1. 分区键:io_state(输入输出)、global_state(全局)、comp_state(组件)、workflow_state(工作流)、agent_state(agent)、trace_state(链路追踪),以及对应的 *_updates 待提交更新键。工作流状态快照就是一张以这些键为 key 的 Map,WorkflowStateCollection.getState() 导出的正是 io/global/comp/workflow 四个分区组成的映射;
  2. 默认标识:DEFAULT_NODE_ID = "default" 与 DEFAULT_WORKFLOW_ID = "workflow",用于根节点和默认工作流分区的引用。

State 的方法分为四组:

  • getGlobal(key) / updateGlobal(data):读写全局状态分区;
  • get(key) / update(data):读写组件/局部状态(在工作流实现中按当前 nodeId 包装,见后文);
  • updateTrace(span):写入当前节点的 trace 数据;
  • getState() / setState(state) / dump():快照恢复与调试导出。其中 dump() 返回已提交状态 + 待提交更新的完整调试视图,而 getState() 只导出已提交的分区快照,两者区别在 WorkflowStateCollection.dump() 中体现得很清楚——dump() 额外包含 io_state_updates、global_state_updates、comp_state_updates、workflow_state_updates 四个待提交区。

另外还有一个不列入类型表的 SessionStateAccess 接口,它是 BaseSession 等调用方共用的状态表面:只强制要求 get(key) 和 update(data),其余方法(getGlobal、updateGlobal、updateTrace、dump、getState、setState)都给了宽松默认值(返回 null / 空 Map / 空实现),用于兼容那些只提供局部状态读写的轻量实现。

三、InMemoryStateLike:带深拷贝的内存状态实现

InMemoryStateLike 是 StateLike 的内存实现,也是整个状态包的基石。它有三个关键设计点:

1. 对外一律返回深拷贝。 get(key) 和 getState() 返回的都是通过 deepCopy 复制出的 Map/List,嵌套结构也会递归复制(不可复制的值类型原样返回)。这样调用方拿到快照后随意修改,都不会污染状态对象内部数据。测试 StateTest 中有直接验证:

// StateTest.testGetStateDeepCopy
InMemoryStateLike state = new InMemoryStateLike(Map.of("key", "value"));
Map<String, Object> copy = state.getState();
copy.put("newKey", "newValue");
assertNull(state.get("newKey")); // 原始状态不受影响

2. update 做嵌套合并。 update(data) 经由 SessionUtils.updateDict 把传入数据合并进内部状态:先对 data 深拷贝再合并,避免外部 Map 被内部状态持有。对嵌套 Map,行为是"合并不覆盖"——测试 testUpdateMergesNested 验证了初始 data.a=1,更新 data.b=2 后 a、b 同时存在。

3. 全部方法 synchronized。 get、update、getState、setState 均加了同步修饰,状态对象可以安全地在多线程的节点执行场景中被共享。

public class InMemoryStateLike implements StateLike {

    private Map<String, Object> state;

    public InMemoryStateLike(Map<String, Object> initialState) {
        this.state = initialState == null ? new LinkedHashMap<>() : deepCopyMap(initialState);
    }

    @Override
    public synchronized Object get(Object key) {
        return deepCopy(SessionUtils.getBySchema(key, state));
    }

    @Override
    public synchronized void update(Map<String, Object> data) {
        SessionUtils.updateDict(deepCopyMap(data), state);
    }
    // getByPrefix / getByTransformer / getState / setState 略
}

注意 getByTransformer(transformer) 是把内部原始状态直接交给转换函数处理的,不经过深拷贝,适合"只读提取"型场景。

四、InMemoryCommitState:待提交缓冲区与提交/回滚

InMemoryCommitState 在 StateLike 之上实现了 CommitStateLike,核心是一个 Map<String, List<Map<String, Object>>> updates 待提交缓冲区,按 nodeId 分组缓存更新。其事务语义如下:

方法 行为(源码依据:InMemoryCommitState.java)
update(data) 直接抛异常。提交型状态不允许无节点上下文的更新,强制调用方显式提供 nodeId。
updateById(nodeId, data) 把一份深拷贝后的更新追加到该节点的待提交列表;nodeId = null 时抛异常。
commit(nodeId) 将指定节点的全部待提交更新依次应用到底层 state,然后清空该节点缓冲区;nodeId = null 时提交所有节点的全部待提交更新并清空整个缓冲区。
rollback(nodeId) 清空指定节点的待提交更新,底层已提交状态不受影响。
getUpdates() / setUpdates(updates) 导出/恢复待提交缓冲区,使事务中间态可快照化。
get/getByPrefix/getByTransformer/getState/setState 全部透传到底层 StateLike,读取的始终是已提交的数据。

StateTest 对这条事务链有完整验证(StateTest.java):

InMemoryCommitState commitState = new InMemoryCommitState();
commitState.updateById("node1", Map.of("key", "value"));
assertNull(commitState.get("key"));          // 提交前读不到
commitState.commit("node1");
assertEquals("value", commitState.get("key"));  // 提交后可读

// rollback 场景
commitState.updateById("node1", Map.of("key", "value"));
commitState.rollback("node1");
commitState.commit("node1");
assertNull(commitState.get("key"));  // 回滚后提交也不会落盘

正是"先缓冲、后落盘"的机制,让工作流在节点执行失败时可以整节点回滚,而不会留下半提交状态。

五、WorkflowStateCollection 与 WorkflowCommitState:四分区工作流状态

5.1 四分区集合

WorkflowStateCollection 是 State 的工作流实现,同时持有四个 CommitStateLike 分区——ioState(IO)、globalState(全局)、compState(组件)、workflowState(工作流)——外加 traceState 缓存以及 parentId/nodeId 节点标识。构造时 parentId 缺省为空字符串,nodeId 缺省为 State.DEFAULT_NODE_ID。

其读写路由规则值得细看:

  • update(data):把组件状态包装在当前 nodeId 之下(wrappedData.put(nodeId, data))再写入 compState 的待提交区。即组件状态按节点隔离,get(key) 通过 compState.getByPrefix(key, nodeId) 读回当前节点的那一段;key = null 时返回节点整段状态;
  • getGlobal(key):优先读 globalState;若缺值则依次回退到 ioState.getByPrefix(key, parentId) 和 ioState.getByPrefix(key, nodeId)——即全局读取带有"父节点 IO → 当前节点 IO"的兜底链路;
  • updateGlobal(data):记入当前节点对应的全局状态待提交区(globalState.updateById(nodeId, data)),并非立即生效;
  • commitCmp():只提交当前节点的 compState 与 ioState,用于节点完成时的局部提交。

5.2 WorkflowCommitState:节点级状态分区与提交/回滚

WorkflowCommitState 继承 WorkflowStateCollection,在其上补齐了完整的提交/回滚/节点派生能力,是 Session 层最常用到的状态对象。关键方法:

public void commit() {
    ioState.commit(null);
    compState.commit(null);
    globalState.commit(null);
    workflowState.commit(null);
}

public void rollback() {
    compState.rollback(nodeId);
    ioState.rollback(nodeId);
    globalState.rollback(nodeId);
    workflowState.rollback(nodeId);
}

public WorkflowCommitState createNodeState(String newNodeId, String newParentId) {
    return new WorkflowCommitState(ioState, globalState, compState, workflowState,
            traceState, newParentId, newNodeId);
}
  • commit() 把四个分区中所有节点的待提交更新一次性落盘;而 rollback() 只针对当前节点做回滚,粒度差异是理解执行流程的关键;
  • createNodeState(newNodeId, newParentId) 用共享的四个分区对象创建一个新的节点级状态对象——父子节点共享同一份分区存储,但各自维护独立的 nodeId/parentId 视角,这正是"节点级状态分区"的实现方式:每个节点看到的状态是按自身 nodeId 前缀隔离的子集;
  • IO 分区辅助方法:setOutputs(data) 把当前节点输出以 nodeId 为前缀写入 ioState 待提交区;getInputs(schema) / getOutputs(targetNodeId) 通过 getByPrefix 按前缀解析节点输入输出;commitUserInputs(inputs) 把用户输入同时写入 IO 与全局分区并立即 commit();
  • getState()/setState() 导出/恢复 io/global/comp/workflow 四分区快照;getUpdates()/setUpdates() 额外处理四分区各自的 *_updates 待提交区,保证 checkpointer 持久化的不只是已提交状态,还包括未提交的事务中间态。

5.3 在 Session 与图执行中的真实使用

WorkflowCommitState 是 graph 执行与检查点机制的交汇点。从源码结构看:

  • graph/AtomicNode.java 中的 validateSessionAndState(session) 会把 Session 携带的状态校验为 WorkflowCommitState 后交给原子节点执行,图节点在执行时通过它读写分区状态;
  • checkpointer/InMemoryCheckpointer.java 在保存/恢复检查点时,多次对 session.state() 做 instanceof WorkflowCommitState 判断,利用其 getState()/setState() 快照与 getUpdates()/setUpdates() 待提交区完成状态持久化与中断恢复;
  • graph/Vertex.java 与 graph/stream_actor/ActorManager.java 同样以 WorkflowCommitState 作为节点执行期的状态载体。

对使用者而言这意味着:只要 Session 的状态是 WorkflowCommitState,中断恢复、检查点、节点级回滚等能力即可自动生效;自定义状态实现时需要至少覆盖 RecoverableState 的快照接口并保持 State 的分区键约定。

六、AgentStateCollection 与 InMemoryState 工厂

6.1 Agent 侧的两分区实现

AgentStateCollection 是 State 的 agent 侧实现,只管理 globalState 与 agentState 两个 InMemoryStateLike 分区(外加空的 traceState 缓存),且不引入待提交缓冲:

  • get(key) / update(data):读写 agent 状态分区,key = null 时返回完整 agent 状态映射;
  • getGlobal(key) / updateGlobal(data):读写全局分区,key = null 时返回完整全局映射;
  • getState()/setState():导出/恢复 global_state + agent_state 组成的快照;dump() 额外附带 trace_state;
  • updateTrace(span) 当前为空实现(与 Python 版行为一致);另提供 getGlobalStateLike() 暴露内部全局状态对象。

从源码结构看,Agent 场景(如 ReAct 循环)不需要节点级事务,因此直接使用直写的 InMemoryStateLike,与工作流侧的 InMemoryCommitState 形成对照。

6.2 InMemoryState:一行构造完整工作流状态

InMemoryState 是私有构造的工厂类,用于快速组装内存版 WorkflowCommitState:

// 空状态
WorkflowCommitState state = InMemoryState.create();

// 携带初始分区数据(任一分区可传 null)
WorkflowCommitState state = InMemoryState.create(ioState, globalState, compState,
        workflowState, traceState);

// 从 getState()/快照 Map 恢复
Map<String, Object> snapshot = state.getState();
WorkflowCommitState restored = InMemoryState.fromMap(snapshot);

fromMap(stateMap) 按 io_state、global_state、comp_state、workflow_state、trace_state 五个键解包快照,null 入参会退化为空的 create();新建的状态对象使用 parentId = ""、nodeId = State.DEFAULT_NODE_ID 作为根节点视角。这个"快照 Map → 状态对象"的往返正是快照恢复流程中最常用的一对操作,session/internal/WorkflowSession.java 与 workflow/Workflow.java 等 Session/工作流入口都通过该工厂构建初始状态。

七、类型关系总结与验证入口

把整个包串起来,类型关系可以概括为一条继承链加两条集合实现:

ReadableState ─┐
               ├─ StateLike ── CommitStateLike ──┐
RecoverableState ┘                               │
                                                 │(分区组件)
SessionStateAccess ── State ◄─ WorkflowStateCollection ◄─ WorkflowCommitState
                     ◄─ AgentStateCollection
InMemoryStateLike implements StateLike
InMemoryCommitState implements CommitStateLike(底层复用 StateLike)
InMemoryState ── 工厂 ──► WorkflowCommitState
  • 需要只读 + 快照(检查点、调试)时依赖 ReadableState/RecoverableState;
  • 需要事务语义(节点级缓冲、提交/回滚)时实现 CommitStateLike,参考 InMemoryCommitState;
  • 组装完整工作流 Session 状态时直接用 InMemoryState.create()/fromMap();
  • 组装 Agent 侧状态时用 new AgentStateCollection()。

功能验证可以运行状态包的专属测试 core/src/test/java/com/openjiuwen/core/session/state/StateTest.java(覆盖 InMemoryStateLike 深拷贝与嵌套合并、InMemoryCommitState 的 updateById/commit/rollback 全链路、以及 WorkflowCommitState/AgentStateCollection 的快照往返),相关文档也提到 AgentSessionApiTest、SessionBasicTest、SessionTest、StreamOutputTest、WorkflowInteractionTest 等测试间接覆盖这些类型;Session 层整体行为可结合 session.README.md 与 Checkpointer检查点机制 继续阅读。

登录后查看全文
agent-core-java