会话记忆

多轮对话里，模型不是自动“记住”一切。它只看得见下一次请求上下文里的内容。Session 负责把对话历史保存下来，并从完整历史里维护一个真正放进下一次请求的窗口。

Session 适合管理当前对话。它不是知识库，也不是跨任务的证据仓库。做长程任务时，可以把 Session 当“当前对话归属”，把 Workspace 当“任务证据和产物归属”，把 TriggerFlow execution 当“当前流程归属”。

启用一个 session

from agently import Agently

agent = Agently.create_agent()
agent.activate_session(session_id="support-demo")

await agent.input("请记住：我的订单号是 A-100。").get_result().async_get_text()
reply = await agent.input("我的订单号是什么？").get_result().async_get_text()

agent.deactivate_session()

activate_session(session_id=...) 会创建或复用这个 id 对应的 Session，并把 runtime.session_id 写进 agent settings。deactivate_session() 后，agent 不再把 session chat history 注入请求。

它保存两层内容

名称	含义
full_context	完整对话历史
context_window	真正进入下一次请求的窗口

默认策略只做长度控制。当 context_window 超过 session.max_length，默认 handler 会从最新消息往前保留，直到不超过限制。如果最后一条消息也超长，就截取这条消息末尾。

agent.set_settings("session.max_length", 12000)

这个长度是按消息序列化后的字符数近似，不是精确 token 计数。

手动管理 chat history

启用 session 后，agent 上这些方法会代理到当前 session：

agent.set_chat_history([
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好，我是 Agently 助手。"},
])

agent.add_chat_history({"role": "user", "content": "继续上个话题"})
agent.reset_chat_history()

当前 session 在 agent.activated_session。没有启用 session 时，这些方法会退回普通 agent prompt 的 chat history 行为。

控制记录哪些内容

默认情况下，请求结束后，session 会把本次 prompt 文本作为 user 内容、把结果数据作为 assistant 内容追加到历史。

想只记录部分字段时：

agent.set_settings("session.input_keys", ["info.task", "input.question"])
agent.set_settings("session.reply_keys", ["answer", "score"])

session.input_keys 从 prompt 数据里取路径；session.reply_keys 从解析后的结果数据里取路径。设为 None 时恢复默认记录方式。

memo 不是自动摘要

内置 Session 不会自动调用模型生成摘要。memo 是一个可序列化字段，供自定义 resize handler 写入：

def analysis_handler(full_context, context_window, memo, session_settings):
    if len(context_window) > 6:
        return "keep_last_four"
    return None


def keep_last_four(full_context, context_window, memo, session_settings):
    new_memo = {
        "previous_turns": len(full_context) - 4,
        "note": "Older turns were summarized by application code.",
    }
    return None, list(context_window[-4:]), new_memo


agent.register_session_analysis_handler(analysis_handler)
agent.register_session_resize_handler("keep_last_four", keep_last_four)

如果要做“模型摘要记忆”，把模型调用放进自己的 resize handler。Session 只负责保存 handler 返回的 memo 并在后续请求里注入它。

导入和导出

from agently.core import Session

session = agent.activated_session
json_text = session.get_json_session()
yaml_text = session.get_yaml_session()

restored = Session(settings=agent.settings)
restored.load_json_session(json_text)

agent.sessions[restored.id] = restored
agent.activate_session(session_id=restored.id)

也可以用别名：session.to_json() / session.to_yaml()、session.load_json(...) / session.load_yaml(...)。

Session、KB、Workspace 怎么选

需求	选什么
当前对话里的历史	Session
大规模文档检索	Knowledge Base
跨 turn 任务证据、artifact、checkpoint	Workspace
跨设备长期用户画像	应用层用户系统
精确 token 预算和高级摘要	自定义 resize handler 或应用层策略

长程任务里不要只问“要不要记忆”。先问这是谁的哪次任务、哪些信息要复核、哪些步骤要恢复。对应的设计路径见 长程任务状态与恢复 Playbook。

常见误用

• 以为 Session 会自动生成长期摘要。
• 把知识库文档塞进 chat history。
• 把任务证据和命令输出塞进 session，而不是 Workspace。
• 以为 session.max_length 是精确 token 预算。
• 忘记 deactivate_session()，导致后续请求继续带历史。

下一步

• 背景信息放哪里：Context Engineering
• 知识库检索：知识库
• 持久任务记录：Workspace
• 长程任务状态与恢复：长程任务状态与恢复 Playbook
• Prompt 槽位：Prompt 管理