Harness profiles 让你打包 Deep Agents 在选择某个 provider 或特定 model 时应用的配置：system prompt 调整、tool description overrides、excluded tools 或 middleware、extra middleware，以及 general-purpose subagent edits。它们是在不更改 create_deep_agent 调用位置的情况下，为特定 model 调整 harness 行为的主要方式。在 Python 中构建 profiles 时使用 HarnessProfile；在 loading or saving YAML/JSON files 时使用 HarnessProfileConfig。Deep Agents 为 OpenAI 和 Anthropic (Claude) models 提供 built-in harness profiles。 Provider profiles 是一个范围更窄的 companion API，用于 model-construction kwargs，不会影响 harness。多数调用方不需要它们；当你希望 provider choice 自带 init_chat_model defaults、credential checks 或 runtime-derived kwargs 时再使用它们，例如打包 provider integration 时。

​
Harness profiles

HarnessProfile 描述 create_deep_agent 在 chat model 构建完成后应用的 prompt assembly、tool visibility、middleware 和 default subagent 调整： 
from deepagents import (
    GeneralPurposeSubagentProfile,
    HarnessProfile,
    register_harness_profile,
)

register_harness_profile(
    "openai:gpt-5.4",
    HarnessProfile(
        system_prompt_suffix="Respond in under 100 words.",
        excluded_tools={"execute"},
        excluded_middleware={"SummarizationMiddleware"},
        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
    ),
)
​
base_system_prompt
string
替换 base Deep Agents system prompt（Prompt assembly 中的 CUSTOM）。
​
system_prompt_suffix
string
向 assembled base prompt 追加文本（Prompt assembly 中的 SUFFIX）；应用于 main agent、declarative subagents，以及自动添加的 general-purpose subagent。
​
tool_description_overrides
Mapping[str, str]
覆盖单个 tool descriptions，以 tool name 为 key。
​
excluded_tools
frozenset[str]
从 tool set 中移除特定 harness-level tools。按 tool name（string）匹配，并作为 post-injection filter 应用，因此可以移除 user-supplied tools 和 harness middleware 添加的 tools。请参阅 Running without the default filesystem tools 获取完整示例。
​
excluded_middleware
frozenset[type[AgentMiddleware] | str]
从 stack 中移除特定 middleware classes。接受 middleware classes 或 string names。
​
extra_middleware
Sequence[AgentMiddleware] | Callable[[], Sequence[AgentMiddleware]]
向此 profile 适用的每个 stack 追加 middleware。
​
general_purpose_subagent
GeneralPurposeSubagentProfile
禁用、重命名或重新提示 general-purpose subagent。当此 field 的 system_prompt 与 base_system_prompt 同时设置时，general-purpose-specific subagent prompt 优先。请参阅 General-purpose subagent prompt。
Caller-supplied system_prompt= 始终位于 assembled prompt 的开头，system_prompt_suffix 始终位于末尾，无论选择哪个 model。相同的 overlay rules 也适用于 subagents：每个 subagent 都会针对自己的 model 重新运行 profile resolution。请参阅 Prompt assembly 获取按场景划分的完整说明（main agent、subagents 和 general-purpose subagent）。
若要运行不带 task tool 的 agent，请参阅 Running without subagents：设置 general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)，并且不要通过 subagents= 传入 synchronous subagents。只有至少存在一个 synchronous subagent 时，SubAgentMiddleware（以及 task tool）才会附加，因此此配置会干净地排除它。Async subagents 不受影响。在 excluded_middleware 中列出 FilesystemMiddleware、SubAgentMiddleware 或 internal permission middleware 会引发 ValueError，因为它们是 required scaffolding。若要在不移除 middleware 的情况下向 model 隐藏它们的 tools，请改用 excluded_tools。请参阅 Running without the default filesystem tools。
excluded_middleware 中的 entries 接受两种形式：
  • Middleware class（按 exact type 匹配），或与 AgentMiddleware.name 匹配的 plain string。对 built-ins 和 public aliases（例如 "SummarizationMiddleware"）使用 plain strings。
  • module:Class import ref（例如 "my_pkg.middleware:TelemetryMiddleware"），用于从 config file 指向 exact middleware class。Import refs 会 lazy resolve，因此只能用于可信的 local configuration，加载它会 import Python code。
当你传入 preconfigured chat model instance 而不是 provider:model string 时，harness 会从该 instance 合成 canonical provider:identifier key，并按以下顺序查找：
  1. Exact provider:identifier match
  2. Identifier-only（仅当 identifier 已包含 : 时）
  3. Provider-only fallback

​
Registration keys

两种 profile types 使用相同的 key format：
  • Provider-level：像 "openai" 这样的 bare provider name 会应用于该 provider 的每个 model。
  • Model-level：像 "openai:gpt-5.4" 这样的 fully qualified provider:model key 只应用于该特定 model。
当 provider-level 和 model-level profile 同时存在时，它们会在 resolution time 合并。未设置的 model-level fields 会继承 provider-level profile；显式 model-level values 会覆盖它们。 在现有 key 下重新注册时，会将新 profile 合并到先前 profile 之上，而不是替换它。请参阅 Merge semantics 获取 per-field rules。
没有可以匹配每个 provider 的 wildcard key。若要在所有地方应用相同 overrides，例如无论选择哪个 model 都移除 TodoListMiddleware，请在你使用的每个 provider key 下注册该 profile。Profiles 适用于依赖所选 model 的调整。无论 model 如何都应应用的 global adjustments 应在 create_deep_agent 调用位置完成。

​
Merge semantics

FieldMerge behavior
base_system_prompt, system_prompt_suffix设置时 new value wins；否则继承
tool_description_overridesMappings 按 key 合并；shared key 上 new value wins
excluded_tools, excluded_middlewareSet union
extra_middleware按 concrete class 合并：new instance 在原位置替换 existing instance，novel classes 追加
general_purpose_subagent按 field 合并（unset fields inherit）
init_kwargs (provider)Dicts 按 key 合并；shared key 上 new value wins
pre_init (provider)Callables chain：existing 先运行，然后运行 new one
init_kwargs_factory (provider)Factories chain，并在每次 resolve_model call 时合并其 outputs

​
Provider profiles

ProviderProfile 声明 Deep Agents 应如何为给定 provider 或 specific model spec 构建 chat model。它只在创建 deep agent 时提供 provider:model string 的情况下应用；如果通过 init_chat_model 传入 preconfigured 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 的 static initialization arguments。
​
pre_init
Callable[[str], None]
在 construction 前运行的 side effects（例如 credential validation）。
​
init_kwargs_factory
Callable[[], dict[str, Any]]
从 runtime state 派生的 kwargs（例如从 environment variables 拉取的 headers）。

​
Load profiles from config files

对于 YAML/JSON-backed workflows，请使用 HarnessProfileConfig。它映射 HarnessProfile 的 declarative subset（prompt text、tool-description overrides、excluded tools and middleware、general-purpose subagent edits），并提供 to_dict / from_dict。Runtime-only state，例如 middleware instances、factories，以及 class-form excluded_middleware entries，仍保留在 HarnessProfile 上。 register_harness_profile 接受任一类型，因此 config-backed callers 不需要手动转换步骤： 
# 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

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)),
    )
若要反向转换，当 runtime profile 只使用 serializable features 时，HarnessProfileConfig.from_harness_profile(...) 可以将其导出回 declarative shape：
  • Class-form excluded_middleware entries 会序列化为 public alias（当 class 通过 serialized_name: ClassVar[str] 暴露一个 alias 时）或 module:Class import ref。
  • Non-empty extra_middleware 以及在 __main__ 或 function scope 内声明的 middleware classes 无法序列化，export 会引发 ValueError。

​
Ship a profile as a plugin

Distributable profiles 可以通过 importlib.metadata entry points 自行注册，而不需要调用方手动运行 register_*_profile。Load order 是 built-ins first, then entry-point plugins, then any direct register_*_profile calls in user code；三条路径都会进入相同的 additive registration，因此 under the same key 时 later registrations 会叠加在 earlier ones 之上。 在 distribution 自己的 pyproject.toml 中，在相应 group 下声明 entry point： 
[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"
每个 target 都会 resolve 为 zero-arg callable，并在 import deepagents.profiles 时执行 registrations： 
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}),
    )
  • Harness：harness capabilities overview
  • Models：配置 model providers 和 parameters
  • Customization：完整的 create_deep_agent configuration surface
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.