配置文件

打包深度智能体在选择模型时应用的按提供商和按模型的默认配置

框架配置文件和提供商配置文件仅限 Python，需要 deepagents>=0.5.4。它们是公开测试版 API，可能在未来版本中更新。

框架配置文件让你打包深度智能体在选择给定提供商或特定模型时应用的配置：系统提示调整、工具描述覆盖、排除的工具或中间件、额外的中间件，以及通用子智能体编辑。它们是在不更改 create_deep_agent 调用处的情况下调优框架对特定模型行为的主要方式。在 Python 中构建配置文件时使用 HarnessProfile；在加载或保存 YAML/JSON 文件时使用 HarnessProfileConfig。深度智能体为 OpenAI 和 Anthropic（Claude）模型内置了框架配置文件。

提供商配置文件是一个更窄的配套 API，用于模型构建 kwargs，不影响框架。大多数调用者不需要它们；当你需要 init_chat_model 的默认值、凭据检查或运行时派生的 kwargs 作为提供商选择的默认值时使用（例如，打包提供商集成时）。

框架配置文件

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

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

替换基础深度智能体系统提示（提示组装中的 CUSTOM）。

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 一起设置时，通用子智能体特定的提示优先——参阅通用子智能体提示。

调用者提供的 system_prompt= 始终位于已组装提示的前端，system_prompt_suffix 始终位于末尾——无论选择了哪个模型。相同的叠加规则适用于子智能体：每个子智能体针对其自身模型重新运行配置文件解析。参阅提示组装获取完整的逐情况分析（主智能体、子智能体和通用子智能体）。

要不使用 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 代码。

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

当你传入预配置的聊天模型实例而非 provider:model 字符串时，框架从实例合成规范的 provider:identifier 键并按以下顺序查找：

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

注册键

两种配置文件类型使用相同的键格式：

• 提供商级别 — 类似 "openai" 的纯提供商名称适用于该提供商的每个模型。
• 模型级别 — 类似 "openai:gpt-5.4" 的完全限定 provider:model 键仅适用于该特定模型。

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

在现有键下重新注册会将新配置文件合并到先前的配置文件之上——而不是替换它。参阅合并语义了解逐字段规则。

没有匹配所有提供商的通配符键。要将相同的覆盖应用到所有地方——比如无论选择哪个模型都移除 TodoListMiddleware——请在你使用的每个提供商键下注册配置文件。配置文件用于依赖所选模型的调整。应该无论模型如何都适用的全局调整应在 create_deep_agent 调用处进行。

合并语义

字段	合并行为
base_system_prompt、system_prompt_suffix	设置时新值优先；否则继承
tool_description_overrides	映射按键合并；共享键上新值优先
excluded_tools、excluded_middleware	集合并集
extra_middleware	按具体类合并：新实例替换其位置上的现有实例，新类追加
general_purpose_subagent	按字段合并（未设置的字段继承）
init_kwargs（提供商）	字典按键合并；共享键上新值优先
pre_init（提供商）	可调用链：先运行现有的，然后运行新的
init_kwargs_factory（提供商）	工厂链，每次 resolve_model 调用时合并其输出

提供商配置文件

ProviderProfile 声明深度智能体应如何为给定提供商或特定模型规格构建聊天模型。它仅在你创建深度智能体时提供 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（例如从环境变量中拉取的标头）。

从配置文件加载配置

对于 YAML/JSON 支持的工作流，请使用 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

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。

将配置文件作为插件发布

可分发的配置文件可以通过 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 配置接口

---

连接这些文档到 Claude、VSCode 等工具，通过 MCP 获取实时解答。

在 GitHub 上编辑此页面或提交问题。