configuring-model-profiles

能力目标

会写两类配置档的注册代码、知道各自在什么条件下才命中、并能用离线手段确认它真的进了配置——而不是靠问模型「你的系统提示里有没有这句」这种不可靠的验证。

前置

• 已能构造智能体并接入模型（见 bootstrapping-deepagents-env、swapping-agent-models）。
• 一个必须先记住的事实：model 参数传实例时框架原样透传该对象、传字符串时框架会另行构造模型。这条分叉决定了下面两类配置档的命中与否。
• 配置档接口当前标注为测试阶段，可能小幅变动。

实操流程

1. 注册提供方配置档，控制模型怎么被构造。三个注入口分别是静态初始化参数、构造前的副作用钩子、运行时派生参数；注册语义是叠加合并、不是整体替换：

   from deepagents import ProviderProfile, register_provider_profile
   from deepagents._models import resolve_model
   
   register_provider_profile(
       "deepseek",
       ProviderProfile(init_kwargs={"temperature": 0}),
   )
   
   model_str = resolve_model("deepseek:deepseek-chat")
   print(model_str.temperature)   # 0.0 ← 来自配置档的初始化参数
   

2. 让提供方配置档生效的唯一路径是字符串写法。要用它就把 model= 写成 "提供方:型号"：

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

   坚持用预配置实例写法的话，就在构造函数里手动设参数，别指望这类配置档。

3. 查一个提供方当前的内置配置档，避免被隐式默认值绊倒：

   from deepagents.profiles.provider.provider_profiles import get_provider_profile
   print(dict(get_provider_profile("openai:gpt-4o").init_kwargs))
   

   内置的 OpenAI 配置档会默认启用其新版响应接口，换到该家模型时要知道这个默认行为。

4. 注册装具配置档，控制模型造好后智能体怎么跑。它有七个字段：系统提示后缀、整体替换基础系统提示、覆盖工具描述、排除工具、排除中间件、追加中间件、配置默认通用子智能体。键可以是提供方名，也可以是完整的「提供方:型号」：

   from deepagents import HarnessProfile, register_harness_profile
   
   register_harness_profile(
       "deepseek:deepseek-chat",
       HarnessProfile(system_prompt_suffix="[标记] 这段后缀由配置档注入。"),
   )
   

   要把配置写进配置文件就用它的声明式可序列化子集（不含追加中间件字段）；要在代码里运行时注册就用全量类型。

5. 想知道「按型号调优」到底是什么，直接把内置配置档的后缀打印出来看——它就是一段普通文本：

   from deepagents.profiles.harness._openai_codex import _SYSTEM_PROMPT_SUFFIX as CODEX_SUFFIX
   from deepagents.profiles.harness._anthropic_sonnet_4_6 import _SYSTEM_PROMPT_SUFFIX as SONNET_SUFFIX
   print(CODEX_SUFFIX)
   print(SONNET_SUFFIX)
   

   两段后缀格式不同（一段是 Markdown 分节、一段是 XML 标签），对应各模型训练时偏好的系统提示风格。

6. 离线核验配置档是否命中，别去问模型。用查找函数直接取出该模型会拿到的配置档对象：

   from deepagents.profiles.harness.harness_profiles import _harness_profile_for_model
   profile = _harness_profile_for_model(model, None)   # 第二参为 None 即实例路径
   print(MARKER in (profile.system_prompt_suffix or ""))
   

7. 要看行为层证据，就在后缀里放一条可观测的格式指令（例如要求输出末尾打印一个固定格式行），再做挂与不挂两组对照，比较输出差异。

校验回路

• 提供方配置档：字符串路径构造出的模型的对应属性值等于你注册的值（如温度为 0.0）。想再加一层证据，就用温度为 0 时输出确定的特性，同一任务连跑两遍看输出是否完全一致。
• 装具配置档：第 6 步的离线核验返回 True；再做一组挂与不挂后缀的对照，挂的一组输出里出现你埋的固定格式行、不挂的没有，且两组都正常调用了内置工具（说明差异只来自后缀）。
• 反向对照：把同一个后缀注册到一个够不着的键上，离线核验应返回 False——这条确认你的键写对了。

常见陷阱

• 注册成功却完全没生效：提供方配置档在实例路径下静默失效。框架解析 model 时先做类型判断，是模型实例就原样返回，注入配置档那一整段根本没机会执行。同一个注册，字符串路径下温度变成 0.0、实例路径下仍是你构造时写的 0.7。它不是「错的」，只是这条路径上不生效。
• 以为两类配置档行为一致：装具配置档在实例路径下仍能命中——它不走模型解析那条路，而是用模型自报的提供方标识去反查注册表。两者形成非对称：一个失效、一个命中。
• 给某一家注册的配置档意外影响了一批模型：凡是用通用 OpenAI 客户端类包装的模型，自报的提供方标识都是 openai，所以注册在这个键下的装具配置档会被所有兼容端点模型命中。要精确控制就注册到完整的「提供方:型号」键上。
• 问模型「你的系统提示里有没有这个标记」：模型无法自省自己的系统提示，回答不可靠、同一脚本两次跑还会翻转。一律走第 6 步的离线核验。
• 排除装具骨架中间件：文件系统与子智能体两件中间件属于骨架、不可排除，构造时会抛 ValueError 并在消息里给出替代方案。想隐藏某个工具就用排除工具字段，或把默认通用子智能体关掉，而不是去剥骨架。
• 用替身函数拦截注入过程来验证：模块加载时已经完成导入绑定，替换原模块属性影响不到这个已绑定的引用，拦不到调用。看属性值本身比看调用日志更直观可靠。
• 配置档生效不等于行为一定变：后缀里的指令能否被执行，还取决于底层模型的指令遵循能力。遵循能力弱的模型可能注入了也不照做。