Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt

Use this file to discover all available pages before exploring further.

工具链配置文件和提供商配置文件仅限 Python 使用，需要 deepagents>=0.5.4。它们是公开测试版 API，可能会在未来的版本中更新。
工具链配置文件 允许你打包配置，当 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.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
替换基础 Deep Agents 系统提示（提示组装中的 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_middleware 中的条目接受两种形式：
  • 一个中间件类（通过精确类型匹配），或一个匹配 AgentMiddleware.name 的普通字符串。对于内置和公共别名（如 "SummarizationMiddleware"）使用普通字符串。
  • 一个 module:Class 导入引用（例如，"my_pkg.middleware:TelemetryMiddleware"），用于从配置文件中定位一个精确的中间件类。导入引用是延迟解析的，因此仅用于受信任的本地配置——加载一个会导入 Python 代码。
当你传递一个预配置的聊天模型实例而不是 provider:model 字符串时，工具链会从实例中合成规范的 provider:identifier 键，并按以下顺序查找：
  1. 精确的 provider:identifier 匹配
  2. 仅标识符（仅当标识符已包含 : 时）
  3. 仅提供商回退

​
注册键

两种配置文件类型使用相同的键格式：
  • 提供商级别 — 一个裸提供商名称，如 "openai"，适用于该提供商的每个模型。
  • 模型级别 — 一个完全限定的 provider:model 键，如 "openai:gpt-5.4"，仅适用于该特定模型。
当提供商级别和模型级别的配置文件都存在时，它们在解析时合并。未设置的模型级别字段从提供商级别配置文件继承；显式的模型级别值会覆盖它们。 在现有键下重新注册会将新配置文件合并到先前的配置文件之上——它不会替换它。有关每个字段的规则，请参见合并语义。
没有匹配每个提供商的通配符键。要应用相同的覆盖——例如，无论选择哪个模型都丢弃 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 声明 Deep Agents 应如何为给定的提供商或特定模型规范构建聊天模型。它仅在你创建深度代理时提供 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]]
从运行时状态派生的关键字参数（例如，从环境变量中提取的头部）。

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

对于基于 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 上编辑此页面 或 提交问题。