配置文件

运行环境配置文件 让你能够打包 Deep Agents 在选定某个特定提供商或模型时应用的配置：系统提示词调整、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用子智能体编辑。它们是调整运行环境对特定模型行为的主要方式，无需更改你的 create_deep_agent 调用点。在 Python 中构建配置文件时使用 HarnessProfile；当从配置文件加载或保存 YAML/JSON 文件时使用 HarnessProfileConfig。Deep Agents 内置了适用于 OpenAI 和 Anthropic (Claude) 模型的运行环境配置文件。 提供商配置文件 是一个更窄范围的配套 API，用于模型构建的关键字参数，这些参数不影响运行环境。大多数调用者不需要它们；当你需要将 init_chat_model 的默认值、凭据检查或运行时派生的关键字参数作为你的提供商选择的默认值时（例如，在打包一个提供商集成时），可以使用它。

运行环境配置文件

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

from deepagents import (
    GeneralPurposeSubagentProfile,
    HarnessProfile,
    register_harness_profile,
)

register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        system_prompt_suffix="请用少于100个字回应。",
        excluded_tools={"execute"},
        excluded_middleware={"SummarizationMiddleware"},
        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
    ),
)

string

替换基础的 Deep Agents 系统提示词（即系统提示词中的 base 键）。

string

在调用者的 suffix 之后追加文本，放在组装好的系统提示词的最后。应用于主智能体、声明式子智能体以及自动添加的通用子智能体。

Mapping[str, str]

覆盖单个工具的描述，以工具名称为键。

frozenset[str]

从工具集中移除特定的运行环境级工具。通过工具名称（字符串）匹配，作为注入后过滤器应用，因此它可以丢弃用户提供的工具和运行环境中间件添加的工具。有关实际示例，请参见不使用默认文件系统工具运行。

frozenset[type[AgentMiddleware] | str]

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

Sequence[AgentMiddleware] | Callable[[], Sequence[AgentMiddleware]

将中间件追加到此配置文件应用的每个栈中。有关内置排序，请参见默认中间件栈。

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 键，并按以下顺序查找：

精确的 provider:identifier 匹配
仅标识符（仅当标识符本身包含 : 时）
仅提供商回退

注册键

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

提供商级—像 "openai" 这样的纯提供商名称适用于该提供商的所有模型。
模型级—像 "openai:gpt-5.5" 这样完全限定的 provider:model 键仅适用于该特定模型。

当同时存在提供商级和模型级配置文件时，它们在解析时会被合并。未设置的模型级字段从提供商级配置文件继承；显式的模型级值会覆盖它们。在现有键下重新注册会将新配置文件合并到之前的之上——而不是替换它。有关每字段规则，请参见合并语义。

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

合并语义

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

提供商配置文件

ProviderProfile 声明了 Deep Agents 应如何为给定的提供商或特定模型规范构建聊天模型。它仅在你创建深度智能体时提供 provider:model 字符串时应用，而不是在你传递通过 init_chat_model 预配置的模型时应用：

from deepagents import ProviderProfile, register_provider_profile

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

Mapping[str, Any]

转发给 init_chat_model 的静态初始化参数。

Callable[[str], None]

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

Callable[[], dict[str, Any]

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

从配置文件加载配置文件

对于基于 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配置文件") 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="并行批量独立工具调用。"),
    )


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

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

运行环境配置文件

注册键

合并语义

提供商配置文件

从配置文件加载配置文件

将配置文件作为插件发布

相关

​运行环境配置文件

​注册键

​合并语义

​提供商配置文件

​从配置文件加载配置文件

​将配置文件作为插件发布

​相关

运行环境配置文件

注册键

合并语义

提供商配置文件

从配置文件加载配置文件

将配置文件作为插件发布

相关