Agently Docs

English

中文

English

中文

Appearance

English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

会话记忆 ​

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

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

启用一个 session ​

python
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 会从最新消息往前保留，直到不超过限制。如果最后一条消息也超长，就截取这条消息末尾。

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

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

手动管理 chat history ​

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

python
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 内容追加到历史。

想只记录部分字段时：

python
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 写入：

python
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 并在后续请求里注入它。

导入和导出 ​

python
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、checkpointWorkspace
跨设备长期用户画像应用层用户系统
精确 token 预算和高级摘要自定义 resize handler 或应用层策略

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

常见误用 ​

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

下一步 ​