Pi Agent: 会话管理
最后更新：2026-08-31
会话是 Agent 的"记忆胶囊"——保存下来，下次继续；分支出去，探索可能。
1. 什么是会话
会话（Session）是一次完整交互的记录，包含：
- 对话历史
- 上下文状态
- 工具调用记录
- Agent 配置
PYTHON
from pi_agent import Agent, Session
# 创建会话
session = Session(name="project_review")
# 绑定 Agent
agent = Agent(name="reviewer", session=session)
# 对话自动记录到会话中
agent.chat("审查 main.py")
agent.chat("有什么安全问题？")
# 会话包含所有对话记录
print(len(session.messages)) # 4 (2 user + 2 assistant)
2. 会话持久化
(1) 保存到文件
PYTHON
from pi_agent import Agent
agent = Agent(name="tutor")
agent.chat("教我 Python 装饰器")
# 保存会话
agent.session.save("decorator_session.json")
(2) 从文件恢复
PYTHON
from pi_agent import Agent
# 恢复会话
agent = Agent(name="tutor")
agent.session.load("decorator_session.json")
# 继续对话——Agent 记得之前的内容
agent.chat("和类方法装饰器有什么区别？")
(3) 自动保存
PYTHON
agent = Agent(
name="tutor",
auto_save=True,
save_dir="./sessions/"
)
3. 会话分支
分支让你从某个节点创建平行的对话路径：
▶ 示例 1：探索不同方案（难度⭐⭐）
PYTHON
from pi_agent import Agent
agent = Agent(name="architect")
agent.chat("设计一个用户认证系统的架构")
# Agent 给出了 JWT 方案
# 从当前节点创建分支
branch1 = agent.branch(name="jwt_branch")
# 主会话继续
agent.chat("用 OAuth2 重新设计")
# Agent 给出了 OAuth2 方案
# 分支会话继续 JWT 方案
branch1.chat("JWT 方案怎么处理 token 刷新？")
# 两个会话独立发展
print(agent.session.messages) # JWT → OAuth2 路径
print(branch1.session.messages) # JWT → 刷新路径
4. 会话管理 CLI
BASH
# 列出所有会话
pi-agent sessions list
# 查看会话详情
pi-agent sessions show decorator_session
# 恢复会话
pi-agent chat --session decorator_session
# 删除会话
pi-agent sessions delete old_session
# 导出会话
pi-agent sessions export decorator_session --format markdown --output chat.md
5. 会话搜索与标签
(1) 添加标签
PYTHON
agent.session.add_tag("python")
agent.session.add_tag("decorator")
agent.session.add_tag("advanced")
(2) 搜索会话
PYTHON
from pi_agent import SessionManager
manager = SessionManager()
# 按标签搜索
sessions = manager.find_by_tag("python")
# 按日期搜索
sessions = manager.find_by_date("2026-08-28")
# 按内容搜索
sessions = manager.search("装饰器闭包")
(3) CLI 搜索
BASH
pi-agent sessions search "装饰器"
pi-agent sessions list --tag python --date 2026-08-28
6. 会话共享
(1) 导出为 Markdown
PYTHON
agent.session.export("chat.md", format="markdown")
(2) 导出为 JSON
PYTHON
agent.session.export("chat.json", format="json")
(3) 分享给其他 Agent
PYTHON
# 将会话上下文传递给另一个 Agent
new_agent = Agent(name="continuer")
new_agent.session.import_from(agent.session)
new_agent.chat("继续上面的讨论，深入讲讲元类")
Alice 的工作流："我每天结束时保存会话，第二天恢复继续。就像和同一个老师持续学习。"
Bob 的用法："项目评审时，我会把会话导出为 Markdown 发给团队，比截图清晰多了。"
❓ 常见问题
Q 会话文件存在哪里？
A 默认在
~/.pi-agent/sessions/ 目录。可通过 save_dir 参数自定义。Q 会话文件会很大吗？
A 取决于对话轮数和内容。一般 100 轮对话约 50-200KB。图片和长代码会增加大小。
Q 可以合并两个会话吗？
A 可以。用
session.merge(other_session) 合并，消息按时间排序。📖 小节
- 会话记录完整交互过程，支持保存、恢复、自动保存
- 分支功能让你探索不同方案而不影响主线
- 标签和搜索让你快速找到历史会话
- 支持导出为 Markdown/JSON，便于分享和存档
📝 作业
- 基础题（难度⭐）：创建一个会话，进行 5 轮对话，保存后重新加载继续。
- 进阶题（难度⭐⭐）：从一个会话创建两个分支，分别探索不同方案，最后对比结果。
- 挑战题（难度⭐⭐⭐）：实现一个"会话仪表盘"脚本，统计所有会话的标签、轮数、token 消耗。
