Sessions
Session 总览
Session 的职责、生命周期，以及本地和远程模式的统一使用方式
Session 总览
Agent 负责组装工具、plugin、配置和存储位置。模型由宿主在执行前注入；真正承载一次连续对话、历史、流式输出与工具审批的是 Session。
一个 Session 是一条持久化的、线性有序的 Message 序列。你可以离开进程后重新 get() 它，也可以在本地 Agent 与 RemoteAgent 之间复用几乎相同的调用方式。
先记住这条主线
create / get
-> 读取 messages() 初始快照
-> subscribe() 实时变化
-> prompt() 返回 turn handle
-> 处理 delta、part、approval
-> await turn.finished
-> 需要时 stop()、fork() 或 archive()订阅要在 prompt() 前建立。它只发送建立订阅之后的 Mutation，不会补发已经发生的流式输出。
一个完整的本地例子
const session = await agent.sessions.create({
sessionId: "repo-analysis",
});
await session.set({ model });
const initial_page = await session.messages();
render_messages(initial_page.items);
const unsubscribe = session.subscribe((mutation) => {
apply_mutation_to_ui(mutation);
if (
mutation.variant === "part" &&
mutation.type === "tool" &&
mutation.part.state === "approval-required" &&
mutation.part.approval
) {
show_approval_request(mutation.part.approval);
}
});
const turn = await session.prompt({ query: "分析这个仓库的 Session 设计" });
const result = await turn.finished;
if (!result.success) {
show_error(result.error || "Turn failed");
}
unsubscribe();apply_mutation_to_ui() 应按 message_id + revision 合并完整快照；对 delta 只追加增量文本。完整做法见 实时订阅 和 重连与同步。
Session 里有哪些对象
| 对象 | 作用 | 什么时候使用 |
|---|---|---|
SessionMessage | 持久化历史的唯一模型 | 首次加载、重连、历史浏览 |
SessionMutation | 订阅后的实时变化协议 | 流式渲染、工具状态、标题更新 |
TurnHandle | 一次输入归属的执行句柄 | 等待最终结果、停止后检查结果 |
SessionApproval | 当前 Session 的待审批工具请求 | 审批页、后台处理 |
Message 和 Mutation 不要混用：Message 是可恢复的状态快照；Mutation 是把状态变化及时送到客户端的协议。
本地与远程的差异
两者都有 prompt()、stop()、compact()、subscribe()、messages()、approvals() 和 fork()。模型配置边界如下：
| 场景 | 配置模型 |
|---|---|
本地 AgentSession | session.set({ model })，只接收运行时模型实例 |
RemoteAgentSession | 不提供模型配置方法；远程客户端只执行 Session |
| Downcity Agent 项目 | City 保存 execution.modelId 和 Session 覆盖，并在每轮执行前注入模型实例 |
远程客户端不参与模型选择；模型 ID、默认值和恢复策略都属于服务端宿主。
API 地图
- 管理会话：
agent.sessions.create/get/list/archive/archived/clean_archive() - 输入与完成：
session.prompt()、turn.finished - 读取与实时：
session.messages()、session.get_info()、session.subscribe() - 运行控制：
session.stop()、session.set()、session.compact()、session.fork() - 工具审批：
session.approvals()、session.resolve_approval()、session.approval_mode() - 调试上下文：
session.system()、元数据与落盘
下一步
先从 管理 Session 建立会话，再阅读 输入与 Turn 和 Message。