状态管理

public interface StateModule {
    // 保存状态到 Session
    void saveTo(Session session, SessionKey sessionKey);

    // 从 Session 加载状态
    void loadFrom(Session session, SessionKey sessionKey);

    // 从 Session 加载状态（如存在），返回是否成功加载
    default boolean loadIfExists(Session session, SessionKey sessionKey) {
        if (session.exists(sessionKey)) {
            loadFrom(session, sessionKey);
            return true;
        }
        return false;
    }
}

public interface State {
    // 标记接口，无需实现任何方法
}

import io.agentscope.core.session.JsonSession;

// 创建 Session
Session session = new JsonSession(Path.of("sessions"));

// 保存
agent.saveTo(session, "user123");

// 加载（会话不存在时静默跳过）
agent.loadIfExists(session, "user123");

// 加载（会话不存在时抛异常）
agent.loadFrom(session, "user123");

import io.agentscope.core.session.Session;
import io.agentscope.core.state.SessionKey;
import io.agentscope.core.state.SimpleSessionKey;
import io.agentscope.core.state.State;

// 定义状态类
public record UserPreferences(String theme, String language) implements State {}

// 保存单个状态
session.save(sessionKey, "preferences", new UserPreferences("dark", "zh"));

// 获取单个状态
Optional<UserPreferences> prefs = session.get(sessionKey, "preferences", UserPreferences.class);

// 保存状态列表
session.save(sessionKey, "history", List.of(msg1State, msg2State));

// 获取状态列表
List<MsgState> history = session.getList(sessionKey, "history", MsgState.class);

import io.agentscope.core.session.Session;
import io.agentscope.core.state.SessionKey;
import io.agentscope.core.state.State;
import io.agentscope.core.state.StateModule;

public class MyComponent implements StateModule {
    private String data;
    private int counter;

    // 定义组件的状态类
    public record MyState(String data, int counter) implements State {}

    @Override
    public void saveTo(Session session, SessionKey sessionKey) {
        session.save(sessionKey, "myComponent", new MyState(data, counter));
    }

    @Override
    public void loadFrom(Session session, SessionKey sessionKey) {
        session.get(sessionKey, "myComponent", MyState.class)
            .ifPresent(state -> {
                this.data = state.data();
                this.counter = state.counter();
            });
    }
}

import io.agentscope.core.state.SimpleSessionKey;
import io.agentscope.core.state.SessionKey;

// 创建 SessionKey
SessionKey key = SimpleSessionKey.of("user123");

// 获取 session ID
String sessionId = ((SimpleSessionKey) key).sessionId();