> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置文件

> 为深度智能体在选择模型时应用的每提供商和每模型默认值打包

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

**Harness 配置文件**允许你打包深度智能体在选择特定提供商或模型时应用的配置：系统提示调整、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用子智能体编辑。它们是在不更改 `create_deep_agent` 调用处的情况下调整 harness 对特定模型行为的主要方式。在 Python 中构建配置文件时使用 `HarnessProfile`；在[从配置文件加载或保存 YAML/JSON 文件](#load-profiles-from-config-files)时使用 `HarnessProfileConfig`。深度智能体为 OpenAI 和 Anthropic（Claude）模型附带内置 harness 配置文件。

**提供商配置文件**是用于*模型构造*关键字参数的更窄配套 API，不影响 harness。大多数调用者不需要它们；当你需要 `init_chat_model` 默认值、凭证检查或运行时派生的关键字参数作为提供商选择的默认值时使用（例如打包提供商集成时）。

## Harness 配置文件

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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),
    ),
)
```

<ResponseField name="base_system_prompt" type="string">
  替换基础深度智能体系统提示（[提示组装](/oss/python/deepagents/customization#prompt-assembly)中的 `CUSTOM`）。
</ResponseField>

<ResponseField name="system_prompt_suffix" type="string">
  追加文本到组装的基础提示（[提示组装](/oss/python/deepagents/customization#prompt-assembly)中的 `SUFFIX`）；应用于主智能体、声明式子智能体和自动添加的通用子智能体。
</ResponseField>

<ResponseField name="tool_description_overrides" type="Mapping[str, str]">
  覆盖单个工具描述，按工具名称为键。
</ResponseField>

<ResponseField name="excluded_tools" type="frozenset[str]">
  从工具集中移除特定的 harness 级工具。按工具名称（字符串）匹配，作为后注入过滤器应用，因此可以删除用户提供的工具和 harness 中间件添加的工具。参见[不使用默认文件系统工具运行](/oss/python/deepagents/harness#virtual-filesystem-access)获取实例。
</ResponseField>

<ResponseField name="excluded_middleware" type="frozenset[type[AgentMiddleware] | str]">
  从栈中剥离特定的中间件类。接受中间件类或字符串名称。
</ResponseField>

<ResponseField name="extra_middleware" type="Sequence[AgentMiddleware] | Callable[[], Sequence[AgentMiddleware]]">
  向此配置文件适用的每个栈追加中间件。
</ResponseField>

<ResponseField name="general_purpose_subagent" type="GeneralPurposeSubagentProfile">
  禁用、重命名或重新提示通用子智能体。当此字段的 `system_prompt` 与 `base_system_prompt` 一起设置时，通用子智能体特定的提示优先 — 参见[通用子智能体提示](/oss/python/deepagents/customization#general-purpose-subagent-prompt)。
</ResponseField>

<Note>
  调用者提供的 `system_prompt=` 始终位于组装提示的前面，`system_prompt_suffix` 始终位于末尾 — 无论选择了哪个模型。相同的覆盖规则适用于子智能体：每个子智能体针对其自己的模型重新运行配置文件解析。参见[提示组装](/oss/python/deepagents/customization#prompt-assembly)了解完整的逐情况分解（主智能体、子智能体和通用子智能体）。
</Note>

<Warning>
  要运行不带 `task` 工具的智能体，参见[不使用子智能体运行](/oss/python/deepagents/subagents#running-without-subagents) — 设置 `general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)` 且不通过 `subagents=` 传递同步子智能体。`SubAgentMiddleware`（和 `task` 工具）仅在至少存在一个同步子智能体时才附加，因此此配置干净地将其排除。异步子智能体不受影响。

  在 `excluded_middleware` 中列出 `FilesystemMiddleware`、`SubAgentMiddleware` 或内部权限中间件会引发 `ValueError` — 它们是必需的脚手架。要在不移除中间件的情况下从模型中隐藏它们的工具，请使用 `excluded_tools` — 参见[不使用默认文件系统工具运行](/oss/python/deepagents/harness#virtual-filesystem-access)。
</Warning>

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

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

<Accordion title="预配置模型实例的查找顺序">
  当你传递预配置的聊天模型实例而非 `provider:model` 字符串时，harness 从实例合成规范的 `provider:identifier` 键并按以下顺序查找：

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

## 注册键

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

* **提供商级** — 裸提供商名称如 `"openai"` 适用于该提供商的每个模型。
* **模型级** — 完全限定的 `provider:model` 键如 `"openai:gpt-5.4"` 仅适用于该特定模型。

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

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

<Note>
  没有匹配每个提供商的通配符键。要在任何地方应用相同的覆盖 — 例如无论选择哪个模型都删除 `TodoListMiddleware` — 在你使用的每个提供商键下注册配置文件。配置文件旨在用于取决于所选模型的调整。无论模型如何都应适用的全局调整应在 `create_deep_agent` 调用处进行。
</Note>

## 合并语义

| 字段                                          | 合并行为                            |
| ------------------------------------------- | ------------------------------- |
| `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`](https://reference.langchain.com/python/langchain/chat_models/base/init_chat_model) 的预配置模型时：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from deepagents import ProviderProfile, register_provider_profile

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

<ResponseField name="init_kwargs" type="Mapping[str, Any]">
  转发给 `init_chat_model` 的静态初始化参数。
</ResponseField>

<ResponseField name="pre_init" type="Callable[[str], None]">
  构造前运行的副作用（例如凭证验证）。
</ResponseField>

<ResponseField name="init_kwargs_factory" type="Callable[[], dict[str, Any]]">
  从运行时状态派生的关键字参数（例如从环境变量拉取的头部）。
</ResponseField>

## 从配置文件加载配置

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

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

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 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
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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` 中在适当的组下声明入口点：

```toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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` 时执行注册：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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](/oss/python/deepagents/harness) — harness 能力概览
* [模型](/oss/python/deepagents/models) — 配置模型提供商和参数
* [自定义](/oss/python/deepagents/customization) — 完整的 `create_deep_agent` 配置面

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/profiles.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>