Harness 配置文件 允许您打包配置，Deep Agents 在选择给定提供者或特定模型时会应用这些配置：系统提示词调整、工具描述覆盖、排除的工具或中间件、额外的中间件，以及通用子代理编辑。这是调整 Harness 对特定模型行为的主要方式，而无需更改您的 create_deep_agent 调用站点。使用 HarnessProfile 在 Python 中构建配置文件时使用；使用 HarnessProfileConfig 当 loading or saving YAML/JSON files时。Deep Agents 附带了 OpenAI 和 Anthropic (Claude) 模型的内置 Harness 配置文件。

提供者配置文件 是用于 *model-construction* kwargs 的更窄的配套 API，不会影响 Harness。大多数调用者不需要它们；当您想要 init_chat_model 默认值、凭证检查或运行时派生的 kwargs 作为默认值与您的提供者选择一起使用（例如，在打包提供者集成时）。

Harness 配置文件

A 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),
    ),
)

替换基础 Deep Agents 系统提示词（CUSTOM in 提示词组装).

追加文本到组装的基础提示词（SUFFIX in 提示词组装）；应用于主代理、声明式子代理和自动添加的通用子代理。

覆盖单个工具描述，按工具名称键控。

从工具集中移除特定的 Harness 级别工具。按工具名称（字符串）匹配，作为注入后过滤器应用，因此可以同时删除用户提供的工具和 Harness 中间件添加的工具。参见 在没有默认文件系统工具的情况下运行 以获取完整示例。

从 默认栈中剥离特定的中间件类。接受中间件类或字符串名称。

向此配置文件应用的每个栈追加中间件。参见 默认中间件栈 以了解内置顺序。

禁用、重命名或重新提示通用子代理。当此字段的 system_prompt 与...一起设置 base_system_prompt，通用子代理提示词优先——见 通用子代理提示词.

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

• - 中间件 *类* （按精确类型匹配）或匹配 AgentMiddleware.name对于内置项和公共别名，请使用纯字符串，例如 "SummarizationMiddleware".
• - An module:Class 导入引用（例如， "my_pkg.middleware:TelemetryMiddleware") 从配置文件定位特定中间件类。Import 引用延迟解析，因此仅在可信的本地配置中使用——加载时会导入 Python 代码。

注册密钥

两种 profile 类型使用相同的密钥格式：

• Provider-level — 一个裸提供商名称如 "openai" 适用于该提供商的所有模型。
• Model-level — 一个完全限定的 provider:model key 如 "openai:gpt-5.5" 仅适用于该特定模型。

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

使用现有密钥重新注册会将新 profile 合并到先前 profile 之上——不会替换它。参见 合并语义 了解逐字段规则。

合并语义

| init_kwargs （提供商）| 字典按 key 合并；共享 key 时新值优先 | | pre_init (provider) | 可调用对象链：现有先运行，然后是新添加的 | | init_kwargs_factory (provider) | 工厂链，其输出在每次 resolve_model 调用时合并 |

提供者配置

A ProviderProfile 声明了 Deep Agents 如何为给定的提供者或特定模型规范构建聊天模型。仅在您提供 provider:model 字符串创建 deep agent 时适用，而不是在使用 @init_chat_model]:

from deepagents import ProviderProfile, register_provider_profile

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

转发给 init_chat_model.

构造前运行的副作用（例如，凭证验证）。

从运行时状态派生的 Kwargs（例如，从环境变量中提取的请求头）。

从配置文件加载配置

For YAML/JSON-backed workflows, use HarnessProfileConfig。它镜像了 HarnessProfile 的声明式子集（提示文本、工具描述覆盖、排除的工具和中间件、通用子代理编辑）并拥有 to_dict / from_dict。仅运行时状态 — 中间件实例、工厂和类形式的 excluded_middleware 条目 — 保留在 HarnessProfile.

register_harness_profile 接受任一类型，因此基于配置调用方无需手动转换步骤：

# 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

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(...) 当运行时配置仅使用可序列化功能时，会将其导出回声明式形状：

• - Class-form excluded_middleware 条目序列化为公共别名（当类通过 serialized_name: ClassVar[str]) or as a module:Class 导入引用。
• - Non-empty extra_middleware 中声明的类和中间件类 __main__ 或在函数作用域内无法序列化 — 导出会抛出 ValueError.

将配置作为插件发布

可分发配置可以通过 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}),
    )

相关

• - 测试架概述 — 测试架能力概述
• - 模型 — 配置模型提供者和参数
• - 自定义 — 完整 create_deep_agent 配置界面