session.set({ model })

session.set({ model }) 让本地 SDK Session 使用自己的 AgentModel 覆盖 Agent 模型。这里可以直接传入 AI SDK LanguageModel 或 City CityModel。

await session.set({
  model: openai.responses("gpt-5"),
});

运行中切换何时生效

session.set() 成功返回表示新配置已经写入并进入当前 Session 的有序输入队列，不表示正在进行的 provider 请求会被替换。

• 当前流式响应和正在执行的工具继续使用原模型
• 新模型在下一个 Session step 检查点生效；如果当前 Session turn 先结束，则在下一个 Session turn 开始时生效
• 配置修改与运行中追加的 steer prompt 按入队顺序一起提交
• 模型切换生效时，Session timeline 会产生 completed action message

因此，配置 API 的返回值表达“修改是否成功”，action message 表达“修改在哪个 Session turn 的 step 检查点生效”。Timeline 只承担观测职责：action 写入失败不会回滚已经生效的配置，SDK 会记录 warning。

控制 Action 与 Mutation

set() 的第二个可选参数只控制配置提交后的可观测结果，不影响配置写入和检查点生效：

await session.set(
  { model },
  { persist_action: false, publish_mutation: false },
);

• persist_action 默认为 true；设为 false 时不创建配置 Action Message。
• publish_mutation 默认跟随 persist_action；设为 false 时可以保留历史 Action，但不向 subscribe() 发布对应 Mutation。
• persist_action=false 时不能设置 publish_mutation=true，因为 Message Mutation 必须对应 canonical Message。
• 重复设置相同模型身份不会创建新的配置 Action；重启后传入同一模型只会重新绑定运行时实例。

Session 初始化或恢复可关闭两项可观测输出；用户主动切换模型通常保留默认选项。

什么时候需要它

适用于这些场景：

• 你在纯 SDK 嵌入模式下使用 @downcity/agent
• 你直接管理本地 Session

Agent 默认模型

多个 Session 使用同一个模型时，直接在 Agent 上提供实例：

const agent = new Agent({
  id: "repo-helper",
  workspace: new Workspace({ path: "/path/to/project" }),
  model,
});

Session 没有显式模型时会回退到该 Agent 模型；设置后则优先使用自己的模型。模型实例不会持久化。

为什么会这样设计

因为本地 SDK 更像一个嵌入式执行壳：

• agent 负责路径、工具、plugin、会话落盘
• 具体用哪个运行中的模型实例，由调用方决定

这让本地 SDK 更灵活，但也把“模型是否准备好”的责任明确交给了调用方。

如果不设置会怎样

如果 Agent 和本地 Session 都没有模型实例，执行会明确失败。

远程 session 呢

远程 Session 不提供模型设置 API。远程客户端只发送 prompt；服务端创建本地 Agent 时传入模型实例。

Downcity Agent 项目呢

如果你是在正常的 Downcity Agent 项目里工作，模型通常应该来自：

• Agent config execution.modelId
• 已连接的 Federation AIService

这时不应把 session.set({ model }) 当成默认用法。