框架配置档案（Harness profiles） 让你打包 Deep Agents 在选定某个提供商或特定模型时应用的配置：系统提示词调整、工具描述覆盖、排除的工具或中间件、额外的中间件，以及通用子智能体编辑。它们是调整框架在特定模型下行为的主要方式，而无需更改你的 create_deep_agent 调用点。在 Python 中构建配置档案时使用 HarnessProfile；从配置文件加载或保存 YAML/JSON 文件时使用 HarnessProfileConfig。Deep Agents 为 OpenAI 和 Anthropic（Claude）模型内置了框架配置档案。

提供商配置档案（Provider profiles） 是一个范围更窄的配套 API，用于模型构造 kwargs，它们不会影响框架。大多数调用者不需要它们；当你想让 init_chat_model 默认值、凭据检查或运行时派生的 kwargs 作为与提供商选择一起的默认值时（例如，在打包提供商集成时），可以使用它们。

框架配置档案（Harness profiles） 让你打包 Deep Agents 在选定某个提供商或特定模型时应用的配置：系统提示词调整、工具描述覆盖、排除的工具或中间件、额外的中间件，以及通用子智能体编辑。它们是调整框架在特定模型下行为的主要方式，而无需更改你的 createDeepAgent 调用点。构建配置档案时使用 HarnessProfileOptions；从配置文件加载或保存 YAML/JSON 文件时使用 parseHarnessProfileConfig。Deep Agents 为 OpenAI 和 Anthropic（Claude）模型内置了框架配置档案。

INFO

提供商配置档案（用于控制模型构造 kwargs）和插件注册系统是仅 Python 的功能。TypeScript SDK 只支持框架配置档案。

框架配置档案（Harness profiles）

HarnessProfile 描述了 create_deep_agent 在对话模型构建之后应用的提示词组装、工具可见性、中间件和默认子智能体调整：

from deepagents import (
    GeneralPurposeSubagentProfile,
    HarnessProfile,
    register_harness_profile,
)

register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        system_prompt_suffix="Respond in under 100 words.",
        excluded_tools={"execute"},
        excluded_middleware={"SummarizationMiddleware"},
        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
    ),
)

框架配置档案描述了 createDeepAgent 在对话模型构建之后应用的提示词组装、工具可见性、中间件和默认子智能体调整：

import { registerHarnessProfile } from "deepagents";

registerHarnessProfile("openai:gpt-5.5", {
  systemPromptSuffix: "Respond in under 100 words.",
  excludedTools: ["execute"],
  excludedMiddleware: ["SummarizationMiddleware"],
  generalPurposeSubagent: { enabled: false },
});

• base_system_prompt (string)：替换 Deep Agents 的基础系统提示词（系统提示词中的 base 键）。

• system_prompt_suffix (string)：在调用者的 suffix 之后追加文本，放置在组装好的系统提示词的最后。应用于主智能体、声明式子智能体和自动添加的通用子智能体。

• tool_description_overrides (Mapping[str, str])：覆盖单个工具的描述，以工具名称作为键。

• excluded_tools (frozenset[str])：从工具集中移除特定的框架级工具。按工具名称（字符串）匹配，作为注入后的过滤器应用，因此它可以同时丢弃用户提供的工具和框架中间件添加的工具。请参阅在没有默认文件系统工具的情况下运行获取一个可运行的示例。

• excluded_middleware (frozenset[type[AgentMiddleware] | str])：从默认栈中剥离特定的中间件类。接受中间件类或字符串名称。

• extra_middleware (Sequence[AgentMiddleware] | Callable[[], Sequence[AgentMiddleware]])：将中间件追加到该配置档案应用到的每个栈。请参阅默认中间件栈了解内置顺序。

• general_purpose_subagent (GeneralPurposeSubagentProfile)：禁用、重命名或重新提示通用子智能体。当此字段的 system_prompt 与 base_system_prompt 一起设置时，通用子智能体特有的提示词优先——请参阅通用子智能体提示词。

• baseSystemPrompt (string)：替换 Deep Agents 的基础系统提示词（系统提示词中的 base 键）。

• systemPromptSuffix (string)：在调用者的 suffix 之后追加文本，放置在组装好的系统提示词的最后。应用于主智能体、声明式子智能体和自动添加的通用子智能体。

• toolDescriptionOverrides (Record<string, string>)：覆盖单个工具的描述，以工具名称作为键。

• excludedTools (string[])：从工具集中移除特定的框架级工具。按工具名称匹配，作为注入后的过滤器应用，因此它既能捕获用户提供的工具，也能捕获中间件提供的工具。

• excludedMiddleware (string[])：从组装好的栈中剥离特定的中间件。针对每个中间件的 .name 属性匹配。不能包含必需的脚手架名称（FilesystemMiddleware、SubAgentMiddleware）。

• extraMiddleware (AgentMiddleware[] | (() => AgentMiddleware[]))：在用户中间件之后追加到栈中的额外中间件。可以是静态数组，也可以是每次构造智能体时返回新实例的零参数工厂。

• generalPurposeSubagent (GeneralPurposeSubagentConfig)：禁用、重命名或重新提示通用子智能体（enabled、description、systemPrompt）。

INFO

调用者提供的 system_prompt= 始终位于组装好的提示词的最前面，而 system_prompt_suffix 始终位于最后——无论选择哪个模型。相同的叠加规则适用于子智能体：每个子智能体都会针对自己的模型重新执行配置档案解析。请参阅系统提示词了解完整的逐场景细分（主智能体、子智能体和通用子智能体）。

INFO

调用者提供的 systemPrompt 始终位于组装好的提示词的最前面，而 systemPromptSuffix 始终位于最后——无论选择哪个模型。相同的叠加规则适用于子智能体：每个子智能体都会针对自己的模型重新执行配置档案解析。请参阅系统提示词了解完整的逐场景细分（主智能体、子智能体和通用子智能体）。

WARNING

要在没有 task 工具的情况下运行智能体，请参阅在没有子智能体的情况下运行——设置 general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)，并且不要通过 subagents= 传递同步子智能体。SubAgentMiddleware（和 task 工具）只会在至少存在一个同步子智能体时才被附加，因此此配置可以干净地将其排除。异步子智能体不受影响。

在 excluded_middleware 中列出 FilesystemMiddleware、SubAgentMiddleware 或内部权限中间件会引发 ValueError——它们是默认中间件栈中必需的脚手架。要在不移除中间件的情况下向模型隐藏它们的工具，请改用 excluded_tools——请参阅在没有默认文件系统工具的情况下运行。

excluded_middleware 中的条目接受两种形式：

• 中间件类（按精确类型匹配），或与 AgentMiddleware.name 匹配的普通字符串。对内置和公共别名（例如 "SummarizationMiddleware"）使用普通字符串。
• 一个 module:Class 导入引用（例如，"my_pkg.middleware:TelemetryMiddleware"）来从配置文件中定位确切的中间件类。导入引用会惰性解析，因此只对受信任的本地配置使用它们——加载一个会导入 Python 代码。

WARNING

在 excludedMiddleware 中列出 FilesystemMiddleware 或 SubAgentMiddleware 会在构造时抛出异常——它们是必需的脚手架。要在不移除中间件的情况下向模型隐藏它们的工具，请改用 excludedTools。

预配置模型实例的查找顺序

当你传入预配置的对话模型实例而不是 `provider:model` 字符串时，框架会从该实例合成规范的 `provider:identifier` 键，并按以下顺序查找：

1. 精确的 `provider:identifier` 匹配
2. 仅标识符（仅当标识符已包含 `:` 时）
3. 仅提供商回退

注册键

两种配置档案类型使用相同的键格式：

• 提供商级别——像 "openai" 这样的裸提供商名称适用于该提供商的每个模型。
• 模型级别——像 "openai:gpt-5.5" 这样的完全限定 provider:model 键只适用于该特定模型。

当提供商级别和模型级别的配置档案同时存在时，会在解析时合并。未设置的模型级别字段会继承提供商级别配置档案；显式的模型级别值会覆盖它们。

在现有键下重新注册会将新配置档案合并到先前的配置档案之上——它不会替换它。请参阅合并语义了解每个字段的规则。

INFO

没有匹配每个提供商的通配符键。要在所有地方应用相同的覆盖——比如，无论选择哪个模型都丢弃 SummarizationMiddleware——请在你使用的每个提供商键下注册配置档案。配置档案用于依赖所选模型的调整。无论模型如何都应应用的全局调整，应在 create_deep_agent 调用点进行。

INFO

没有匹配每个提供商的通配符键。要在所有地方应用相同的覆盖——比如，无论选择哪个模型都丢弃 SummarizationMiddleware——请在你使用的每个提供商键下注册配置档案。配置档案用于依赖所选模型的调整。无论模型如何都应应用的全局调整，应在 createDeepAgent 调用点进行。

合并语义

字段	合并行为
base_system_prompt, system_prompt_suffix	设置时新值生效；否则继承
tool_description_overrides	映射按键合并；在共享键上新值生效
excluded_tools, excluded_middleware	集合并集
extra_middleware	按名称合并：新实例替换其位置上的现有实例，新条目追加
general_purpose_subagent	按字段合并（未设置的字段继承）

字段	合并行为
baseSystemPrompt, systemPromptSuffix	设置时新值生效；否则继承
toolDescriptionOverrides	映射按键合并；在共享键上新值生效
excludedTools, excludedMiddleware	集合并集
extraMiddleware	按名称合并：新实例替换其位置上的现有实例，新条目追加
generalPurposeSubagent	按字段合并（未设置的字段继承）

| init_kwargs（提供商） | 字典按键合并；在共享键上新值生效 | | pre_init（提供商） | 可调用对象链式执行：现有先运行，然后运行新的 | | init_kwargs_factory（提供商） | 工厂链式执行，其输出在每次 resolve_model 调用时合并 |

提供商配置档案（Provider profiles）

ProviderProfile 声明 Deep Agents 应如何为给定提供商或特定模型规范构造对话模型。它只在创建深度智能体时提供 provider:model 字符串时应用，而不是在传入使用 init_chat_model 预配置的模型时应用：

from deepagents import ProviderProfile, register_provider_profile

register_provider_profile(
    "openai",
    ProviderProfile(init_kwargs={"temperature": 0}),
)

• init_kwargs (Mapping[str, Any])：转发给 init_chat_model 的静态初始化参数。

• pre_init (Callable[[str], None])：在构造之前运行的副作用（例如，凭据验证）。

• init_kwargs_factory (Callable[[], dict[str, Any]])：从运行时状态派生的 kwargs（例如，从环境变量中提取的标头）。

提供商配置档案（用于控制 temperature 等模型构造 kwargs）是仅 Python 的功能，在 TypeScript SDK 中不可用。

从配置文件加载配置档案

对于 YAML/JSON 支持的工作流，使用 HarnessProfileConfig。它镜像了 HarnessProfile 的声明式子集（提示词文本、工具描述覆盖、排除的工具和中间件、通用子智能体编辑），并拥有 to_dict / from_dict。仅运行时状态——中间件实例、工厂和类形式的 excluded_middleware 条目——保留在 HarnessProfile 上。

register_harness_profile 接受这两种类型，因此配置支持的调用者不需要手动转换步骤：

对于 YAML/JSON 支持的工作流，使用 parseHarnessProfileConfig。它从带有 camelCase 键的普通对象验证并构建 HarnessProfile。仅运行时状态（例如 extraMiddleware 实例）无法在 JSON/YAML 中表示，必须以编程方式设置。

# openai.yaml
base_system_prompt: You are helpful.
system_prompt_suffix: Respond briefly.
excluded_tools:
  - execute
  - grep
excluded_middleware:
  - SummarizationMiddleware
  - my_pkg.middleware:TelemetryMiddleware
general_purpose_subagent:
  enabled: false

# profile.yaml
baseSystemPrompt: You are helpful.
systemPromptSuffix: Respond briefly.
excludedTools:
  - execute
  - grep
excludedMiddleware:
  - SummarizationMiddleware
generalPurposeSubagent:
  enabled: false

import yaml
from deepagents import HarnessProfileConfig, register_harness_profile

with open("openai.yaml") as f:
    register_harness_profile(
        "openai",
        HarnessProfileConfig.from_dict(yaml.safe_load(f)),
    )

要反向转换，当 HarnessProfileConfig.from_harness_profile(...) 只使用可序列化的特性时，它会将运行时配置档案导出回声明式形状：

• 类形式的 excluded_middleware 条目会序列化为公共别名（当类通过 serialized_name: ClassVar[str] 暴露一个别名时）或 module:Class 导入引用。
• 非空的 extra_middleware 和在 __main__ 中或函数作用域内声明的中间件类无法序列化——导出会引发 ValueError。

import { readFileSync } from "fs";
import YAML from "yaml";
import { parseHarnessProfileConfig, registerHarnessProfile } from "deepagents";

const raw = YAML.parse(readFileSync("profile.yaml", "utf-8"));
registerHarnessProfile("openai", parseHarnessProfileConfig(raw));

要将配置档案序列化回 JSON/YAML，请使用 serializeProfile：

import { serializeProfile } from "deepagents";

const data = serializeProfile(profile); // JSON-compatible object

带非空 extraMiddleware 的配置档案无法序列化；如果存在中间件实例，serializeProfile 会抛出异常。

将配置档案作为插件发布

可分发的配置档案可以通过 importlib.metadata 入口点自行注册，而不需要调用者手动运行 register_*_profile。加载顺序是内置优先，然后是入口点插件，然后是用户代码中的任何直接 register_*_profile 调用；这三条路径都汇入同一个加法注册，因此较晚的注册会在相同键下叠加在较早的注册之上。

在发行版自己的 pyproject.toml 中，在适当的组下声明一个入口点：

[project.entry-points."deepagents.harness_profiles"]
my_provider = "my_pkg.profiles:register_harness"

[project.entry-points."deepagents.provider_profiles"]
my_provider = "my_pkg.profiles:register_provider"

每个目标解析为一个零参数可调用对象，当 deepagents.profiles 被导入时执行注册：

from deepagents import (
    HarnessProfile,
    ProviderProfile,
    register_harness_profile,
    register_provider_profile,
)

def register_harness() -> None:
    register_harness_profile(
        "my_provider",
        HarnessProfile(system_prompt_suffix="Batch independent tool calls in parallel."),
    )

def register_provider() -> None:
    register_provider_profile(
        "my_provider",
        ProviderProfile(init_kwargs={"temperature": 0}),
    )

插件注册系统（通过包入口点）是仅 Python 的功能。在 TypeScript 中，请在应用程序启动时或在包的初始化代码中直接调用 registerHarnessProfile。

相关

• 框架概述——框架能力概述

• 模型——配置模型提供商和参数

• 自定义——完整的 create_deep_agent 配置面

• 自定义——完整的 createDeepAgent 配置面