程序包 io.agentscope.core.state

接口 AgentStateStore

所有已知实现类:
InMemoryAgentStateStore, JsonFileAgentStateStore
public interface AgentStateStore
Persistent storage interface for AgentScope agent state.

An AgentStateStore provides save / load / delete / list operations for State objects keyed by a (userId, sessionId) pair, allowing agents, memories, toolkits, and other stateful components to be persisted and restored across application runs or user interactions.

Slot addressing is intentionally simple:

  • sessionId — non-null, non-blank; identifies a conversation / session.
  • userId — nullable. null represents an anonymous / single-tenant caller (CLI usage, tests). Implementations group all anonymous sessions under a single namespace.

Implementations decide how to combine the pair into a storage key (filesystem path, Redis key prefix, SQL column). Callers MUST NOT concatenate them manually before calling.

Example usage: 


 AgentStateStore store = new JsonFileAgentStateStore(Path.of("state"));

 // Save state for an anonymous session
 store.save(null, "session-1", "agent_state", state);

 // Save state scoped to a user
 store.save("alice", "session-1", "agent_state", state);

 // Load state
 Optional<AgentState> loaded =
         store.get("alice", "session-1", "agent_state", AgentState.class);

 // List all sessions owned by a user (null lists anonymous sessions)
 Set<String> mySessions = store.listSessionIds("alice");

  • 方法详细资料

    • save

      void save(String userId, String sessionId, String key, State value)
      Save a single state value (full replacement).

      This method saves a single state object, replacing any existing value with the same key.

      参数:
      userId - nullable user identifier; null = anonymous
      sessionId - session identifier; must be non-null and non-blank
      key - the state key (e.g., "agent_state", "toolkit_activeGroups")
      value - the state value to save

    • save

      void save(String userId, String sessionId, String key, List<? extends State> values)
      Save a list of state values.

      Different implementations may use different storage strategies:

      Callers should always pass the full list. The implementation decides the storage strategy.

      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key (e.g., "memory_messages")
      values - the full list of state values

    • get

      <T extends State> Optional<T> get(String userId, String sessionId, String key, Class<T> type)
      Get a single state value.
      类型参数:
      T - the state type
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key
      type - the expected state type
      返回:
      the state value, or empty if not found

    • getList

      <T extends State> List<T> getList(String userId, String sessionId, String key, Class<T> itemType)
      Get a list of state values.
      类型参数:
      T - the item type
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key
      itemType - the expected item type
      返回:
      the list of state values, or empty list if not found

    • exists

      boolean exists(String userId, String sessionId)
      Check if a session exists.
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      返回:
      true if the session has any persisted state

    • delete

      void delete(String userId, String sessionId)
      Delete a session and all its data.
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank

    • delete

      default void delete(String userId, String sessionId, String key)
      Delete a single state entry within a session.
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key to delete

    • listSessionIds

      Set<String> listSessionIds(String userId)
      List session identifiers visible under the given user namespace.

      Use userId == null to list anonymous sessions. Pass a concrete user to list only that user's sessions. There is no API to list across users in one call — that is a separate administrative concern (admin starter handles it by iterating known users).

      参数:
      userId - nullable user identifier
      返回:
      set of session identifiers stored under userId

    • close

      default void close()
      Clean up any resources used by this store. Implementations should override this if they need cleanup.