类class io.agentscope.extensions.postgresql.state 2.x

PostgresAgentStateStore

public class PostgresAgentStateStore implements AgentStateStore

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:58–831

Postgres 智能体状态存储，负责持久化与读取数据。位于 io.agentscope.extensions.postgresql.state 包，实现 AgentStateStore。核心成员包括 supportsVersioning、save、getVersioned、saveIfVersion、get、getList。

PostgreSQL database-based AgentStateStore implementation.

Stores session state in PostgreSQL tables with the following structure:


CREATE TABLE IF NOT EXISTS "agentscope"."agentscope_sessions" (
session_id VARCHAR(255) NOT NULL,
state_key VARCHAR(255) NOT NULL,
item_index INT NOT NULL DEFAULT 0,
state_data TEXT NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (session_id, state_key, item_index)
);

Single state: stored as JSON with item_index = 0
List state: each item stored in a separate row with item_index = 0, 1, 2, ...

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`Builder`	类class	`PostgresAgentStateStore`的构建器。 Builder for `PostgresAgentStateStore`.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `PostgresAgentStateStore(DataSource dataSource)`	创建PostgresAgentStateStore 使用默认设置。 Creates a PostgresAgentStateStore with default settings.
`public` `PostgresAgentStateStore(DataSource dataSource, boolean createIfNotExist)`	初始化 `PostgresAgentStateStore` 实例。 Creates a PostgresAgentStateStore with optional auto-creation.
`public` `PostgresAgentStateStore(DataSource dataSource, String schemaName, String tableName, boolean createIfNotExist)`	初始化 `PostgresAgentStateStore` 实例。 Creates a PostgresAgentStateStore with custom schema/table and optional auto-creation.

方法摘要Method Summary

方法Method	说明Description
`public boolean supportsVersioning()`	返回 `supportsVersioning` 结果。 Returns the supports versioning.
`public void save(String userId, String sessionId, String key,` `State value)`	保存数据到持久化存储。 Performs the save operation.
`public T extends` `State VersionedState<T> getVersioned(String userId, String sessionId, String key, Class<T> type)`	获取 `getVersioned`。 Returns the versioned.
`public long saveIfVersion(String userId, String sessionId, String key,` `State value, long expectedVersion)`	保存If 版本。 Saves the if version.
`public void save(String userId, String sessionId, String key, List<? extends` `State> values)`	保存数据到持久化存储。 Performs the save operation.
`public T extends` `State Optional<T> get(String userId, String sessionId, String key, Class<T> type)`	按条件读取数据。 Performs the get operation.
`public T extends` `State List<T> getList(String userId, String sessionId, String key, Class<T> itemType)`	获取列表。 Returns the list.
`public boolean exists(String userId, String sessionId)`	判断数据是否存在。 Performs the exists operation.
`public void delete(String userId, String sessionId)`	删除数据。 Performs the delete operation.
`public Set<String> listSessionIds(String userId)`	列出 `listSessionIds`。 Lists the session ids.
`public void close()`	关闭连接并释放相关资源。 Releases resources and connections.
`public int truncateAllSessions()`	返回 `truncateAllSessions` 结果。 Truncate session table from the database (for testing or cleanup).
`public String getSchemaName()`	获取模式名称。 Returns the schema name.
`public String getTableName()`	获取 `getTableName`。 Returns the table name.
`public DataSource getDataSource()`	获取数据来源。 Returns the data source.
`protected void validateSessionId(String sessionId)`	校验会话标识。 Validates the session id.
`public static` `Builder builder(DataSource dataSource)` static	返回构建器实例。 Performs the builder operation.

构造器详情Constructor Detail

PostgresAgentStateStore

public PostgresAgentStateStore(DataSource dataSource)

创建PostgresAgentStateStore 使用默认设置。

Creates a PostgresAgentStateStore with default settings.

参数Parameters

名称Name	类型Type	说明Description
`dataSource`	DataSource	数据来源（类型 `DataSource`）。The data source.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:91–93

PostgresAgentStateStore

public PostgresAgentStateStore(DataSource dataSource, boolean createIfNotExist)

初始化 PostgresAgentStateStore 实例。

Creates a PostgresAgentStateStore with optional auto-creation.

参数Parameters

名称Name	类型Type	说明Description
`dataSource`	DataSource	数据来源（类型 `DataSource`）。The data source.
`createIfNotExist`	boolean	创建 If 不 Exist（类型 `boolean`）。The create if not exist.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:101–103

PostgresAgentStateStore

public PostgresAgentStateStore(DataSource dataSource, String schemaName, String tableName, boolean createIfNotExist)

初始化 PostgresAgentStateStore 实例。

Creates a PostgresAgentStateStore with custom schema/table and optional auto-creation.

参数Parameters

名称Name	类型Type	说明Description
`dataSource`	DataSource	数据来源（类型 `DataSource`）。The data source.
`schemaName`	String	模式名称（类型 `String`）。The schema name.
`tableName`	String	table 名称（类型 `String`）。The table name.
`createIfNotExist`	boolean	创建 If 不 Exist（类型 `boolean`）。The create if not exist.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:108–135

方法详情Method Detail

supportsVersioning

public boolean supportsVersioning()

返回 supportsVersioning 结果。

Returns the supports versioning.

返回Returns boolean

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:262–265

save

public void save(String userId, String sessionId, String key, State value)

保存数据到持久化存储。

Performs the save operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`value`	State	值（类型 `State`）。The value.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:267–302

getVersioned

public T extends State VersionedState<T> getVersioned(String userId, String sessionId, String key, Class<T> type)

获取 getVersioned。

Returns the versioned.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`type`	Class<T>	类型（类型 `Class`）。The type.

返回Returns VersionedState<T>

返回VersionedState。Returns versioned state.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:304–331

saveIfVersion

public long saveIfVersion(String userId, String sessionId, String key, State value, long expectedVersion)

保存If 版本。

Saves the if version.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`value`	State	值（类型 `State`）。The value.
`expectedVersion`	long	expected 版本（类型 `long`）。The expected version.

返回Returns long

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:358–393

save

public void save(String userId, String sessionId, String key, List<? extends State> values)

保存数据到持久化存储。

Performs the save operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`values`	List<? extends State>	值（类型 `List`）。The values.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:440–476

get

public T extends State Optional<T> get(String userId, String sessionId, String key, Class<T> type)

按条件读取数据。

Performs the get operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`type`	Class<T>	类型（类型 `Class`）。The type.

返回Returns Optional<T>

返回可选。Returns optional.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:583–609

getList

public T extends State List<T> getList(String userId, String sessionId, String key, Class<T> itemType)

获取列表。

Returns the list.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`itemType`	Class<T>	条目类型（类型 `Class`）。The item type.

返回Returns List<T>

返回列出。Returns list.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:611–637

exists

public boolean exists(String userId, String sessionId)

判断数据是否存在。

Performs the exists operation.

参数Parameters

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

返回Returns boolean

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:639–654

delete

public void delete(String userId, String sessionId)

删除数据。

Performs the delete operation.

参数Parameters

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:656–674

listSessionIds

public Set<String> listSessionIds(String userId)

列出 listSessionIds。

Lists the session ids.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.

返回Returns Set<String>

返回设置。Returns set.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:676–698

close

public void close()

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

Releases resources and connections.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:713–716

truncateAllSessions

public int truncateAllSessions()

返回 truncateAllSessions 结果。

Truncate session table from the database (for testing or cleanup).

返回Returns int

返回数值结果。typically 0 if successful

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:731–740

getSchemaName

public String getSchemaName()

获取模式名称。

Returns the schema name.

返回Returns String

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:742–744

getTableName

public String getTableName()

获取 getTableName。

Returns the table name.

返回Returns String

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:746–748

getDataSource

public DataSource getDataSource()

获取数据来源。

Returns the data source.

返回Returns DataSource

返回DataSource。Returns data source.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:750–752

validateSessionId

protected void validateSessionId(String sessionId)

校验会话标识。

Validates the session id.

参数Parameters

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

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:754–765

builder

public static Builder builder(DataSource dataSource)

static

返回构建器实例。

Performs the builder operation.

参数Parameters

名称Name	类型Type	说明Description
`dataSource`	DataSource	数据来源（类型 `DataSource`）。The data source.

返回Returns Builder

返回当前实例，以支持链式调用。Returns the current instance for chaining.

源码Source io/agentscope/extensions/postgresql/state/PostgresAgentStateStore.java:828–830

嵌套类详情Nested Class Detail

Builder

public static final class Builder

PostgresAgentStateStore的构建器。位于 io.agentscope.extensions.postgresql.state 包。核心成员包括 schemaName、tableName、createIfNotExist、build。

Builder for PostgresAgentStateStore.

继承成员Inherited Members

继承自Members inherited from AgentStateStore

delete, UNVERSIONED