状态与记忆 (History)¶

Agent 的对话历史管理对于长对话和上下文一致性至关重要。by-framework 提供了可插拔的历史存储后端。

存储后端¶

目前支持以下存储方式：

1. Byclaw History (默认)¶

专为 Byclaw 平台优化的存储方案，支持版本管理和结构化检索。

Python

pip install by-framework-history-byclaw

2. Postgres History¶

基于传统关系型数据库的存储方案，适合对数据一致性有要求的场景。

PythonJava

pip install by-framework-history-postgres

使用 JPA 或 JDBC 存储实现，通过 HistoryProvider 接口扩展。

使用方法¶

历史存储后端不是在 Worker 类里覆盖方法指定的，而是通过 HistoryManager 全局注册一次（run_worker() 也提供了一个等价的快捷参数）：

PythonJava

from by_framework_history_postgres import PostgresHistoryBackend
from by_framework.core.runtime.history import HistoryManager

HistoryManager.set_default_backend(
    PostgresHistoryBackend(dsn=os.getenv("DATABASE_URL"))
)

# 或者在启动 Worker 时直接传入，run_worker 内部会调用上面同样的注册逻辑：
# run_worker(worker_class=MyAgent, history_backend=PostgresHistoryBackend(dsn=...))

HistoryManager.setDefaultBackend(new PostgresHistoryBackend(dsn));

核心接口¶

无论使用哪种后端，都要继承 BaseHistoryBackend（Java 同名）并实现三个方法：

get_history(session_id, limit) / getHistory(...)：加载最近的会话记录。
save_message(session_id, message, ...) / saveMessage(...)：保存新的消息。
list_sessions() / listSessions()：列出已有的会话。

Worker 内部通过 context.agent_runtime_state.session_manager.history 访问当前生效的后端实例（SDK 内部使用，业务代码通常不需要直接调用，context.emit_chunk/emit_state 等方法会在流结束时自动触发历史持久化）。