`session.set({ model })`

session.set({ model }) 是本地 SDK Session 绑定运行时模型实例的唯一方式。

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。

什么时候需要它

适用于这些场景：

你在纯 SDK 嵌入模式下使用 @downcity/agent
你直接管理本地 Session
或者你正在实现宿主的 prepare_session 钩子

宿主统一注入

多个 Session 使用统一模型策略时，在 Agent 上提供模型无关的准备钩子：

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  prepare_session: async (session) => {
    const model = await host_model_runtime.resolve(session.id);
    await session.set({ model });
  },
});

SDK 不知道 host_model_runtime 内部使用的模型 ID、默认值或持久化方式。

为什么会这样设计

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

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

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

如果不设置会怎样

如果本地 Session 在执行前没有通过 session.set({ model }) 获得模型实例，执行会明确失败。

远程 session 呢

远程 Session 不提供模型设置 API。远程客户端只发送 prompt；服务端宿主在 prepare_session 中完成模型选择和注入。

Downcity Agent 项目呢

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

Agent config execution.modelId
已连接的 Federation AIService

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

session.set({ model })

目录