swapping-agent-models

能力目标

在不改动任何架构代码的前提下，把一个智能体从一个模型切到另一个模型并验证整套装具在新模型上仍真实运转；同时能给主智能体与子智能体分别配不同模型，做能力与成本分层。

前置

• 已能构造并跑通一个智能体（见 bootstrapping-deepagents-env）。
• 底层模型必须支持工具调用，否则整套工具都不会被触发。
• 准备两个模型来源（两个不同厂商的凭证，或同一厂商的两个型号），才能真正验证「换模型不改架构」。

实操流程

1. 定一条固定任务当基线，两个模型都跑它、并排比对输出，例如「用一句话解释什么是智能体装具，并列出 3 个要点」。

2. 用预配置实例写法接第一个模型。绝大多数国产模型都提供 OpenAI 兼容端点，用这一条路即可：

   import os
   from langchain_openai import ChatOpenAI
   from deepagents import create_deep_agent
   
   model_a = ChatOpenAI(
       model="deepseek-chat",
       base_url=os.environ.get("DEEPSEEK_BASE_URL", "https://api.deepseek.com"),
       api_key=os.environ["DEEPSEEK_API_KEY"],
   )
   agent = create_deep_agent(model=model_a)
   result = agent.invoke({"messages": [{"role": "user", "content": TASK}]})
   

3. 换第二个模型：只改 model= 指向的那个实例，架构代码一字不动：

   model_b = ChatOpenAI(
       model="qwen-plus",
       base_url=os.environ["QWEN_BASE_URL"],       # 兼容端点地址
       api_key=os.environ["QWEN_API_KEY"],
   )
   agent_b = create_deep_agent(model=model_b)
   result_b = agent_b.invoke({"messages": [{"role": "user", "content": TASK}]})
   

4. 需要走提供方字符串写法时，先装对应集成包再用。字符串路径由框架按前缀动态导入集成包，没装就抛带安装指引的 ImportError：

   pip install langchain-deepseek
   

   agent = create_deep_agent(model="deepseek:deepseek-chat")
   

   两条路径的差别要心里有数：传实例时框架原样透传该对象；传字符串时框架会另行构造一个该提供方的专属模型类。同样是接一家模型，两条路径用的是不同的 Python 类。

5. 迁到自己的模型时只替换三个值，其余不动：

   model_b = ChatOpenAI(
       model="你的模型名",
       base_url="你的 OpenAI 兼容端点",
       api_key=os.environ["你的_KEY_环境变量"],
   )
   agent = create_deep_agent(model=model_b)
   

6. 做主子分层：主智能体用强模型编排、子智能体用便宜模型干批量活。子智能体的模型字段接受模型名字符串或已构造的模型对象：

   sub_agents = [{
       "name": "quick_answer_agent",
       "model": model_b,
       "system_prompt": "你是一个简洁回答专家，用一句话回答所有问题。",
       "description": "简洁回答子 Agent，适合快速总结。",
   }]
   agent = create_deep_agent(model="deepseek:deepseek-chat", subagents=sub_agents)
   

校验回路

• 两个模型各跑同一固定任务、各留一份输出，两边都答出可用结果，即「换模型跑得通」成立。
• 换模型后再跑一个明确要求先规划的任务，检查消息列表里出现 write_todos 的工具调用与对应回执——装具在新模型上真干活，不是摆设。
• 做分层时用事件流拦截模型调用结束事件，从返回元数据里读实际命中的模型标识、按事件里的智能体名字段区分主脑子脑，确认两侧确实命中不同模型。
• 算账：把两个模型同一任务的用量元数据打出来对比。注意有缓存命中的一侧提示词 token 数虽高、实际成本却低，看数字前先分清是否命中缓存。价格属高速演变信息，落地前回各厂商官网核当时牌价。

常见陷阱

• 给 OpenAI 兼容端点写错提供方前缀：把某家兼容端点模型写成 "openai:该模型名" 会让请求走 OpenAI 的 Responses API，而该端点不支持，报 404 NotFoundError。接兼容端点用预配置实例写法。
• 以为「换模型不改架构」等于零依赖变更：架构代码确实不改，但字符串写法要求装对应集成包。报错文案会直接告诉你装哪个包，按提示装即可。
• 换了个不支持工具调用的模型：不报错，只是工具永远不被触发、任务安静地做不成。选型先确认该型号支持工具调用。
• 拿官方文档截图里的型号名直接用：型号名属高速演变信息，落地前回对应厂商官网核当时可用型号。
• 在流式输出里找消息：流式片段的键是中间件与节点名（如包裹在模型调用前后的那些节点），不是消息键，直接找消息会取空。要分析工具调用就用一次性调用拿完整消息列表，或按节点名解析片段。
• 忽略兼容端点的提供方标识：用通用 OpenAI 客户端类包装的模型，框架看到的提供方标识一律是 openai，无论它背后接的是哪家。这会影响按型号命中的配置档，详见 configuring-model-profiles。