BytesRouter

主题

LangChain 文档版本 跟随上游 源快照 ec7c511e 更新于 2026-10-08

配置文件

打包 Deep Agents 在选定模型时应用的按服务商和按模型默认值

harness 配置文件 让你可以针对特定模型或服务商自定义 Deep Agents 的 harness。你可以调整系统提示词和工具描述、排除工具或中间件、添加中间件，并配置通用子智能体。只要你选择匹配的模型，Deep Agents 就会应用这些设置，而无需更改你的智能体创建代码。

服务商配置文件 定义创建模型时的默认设置，例如 temperature 和 timeout。这些设置不影响 harness。大多数调用者不需要服务商配置文件。当你要打包一个需要共享默认值、凭据检查或运行时计算设置的集成时，它们会很有用。

harness 配置文件

Deep Agents 包含 内置 harness 配置文件，其中带有针对特定服务商和模型的默认设置。

使用 HarnessProfile 定义 create_deep_agent 在构建聊天模型后应用的设置：

python
from deepagents import (
    GeneralPurposeSubagentProfile,
    HarnessProfile,
    register_harness_profile,
)

register_harness_profile(
    "openai:gpt-6-astra",
    HarnessProfile(
        system_prompt_suffix="Respond in under 100 words.",
        excluded_tools={"execute"},
        excluded_middleware={"SummarizationMiddleware"},
        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
    ),
)

string

设置配置文件的基础指令。对于主智能体，它们跟在调用者的系统指令之后；默认不添加基础指令。对于声明式子智能体，这会替换其编写的系统提示词。

string

在调用者的指令和配置文件的基础指令之后追加文本。应用于主智能体、声明式子智能体以及自动添加的通用子智能体。

Mapping[str, str]

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

frozenset[str]

从工具集中移除特定的 harness 级工具。按工具名称（字符串）匹配，作为注入后过滤器应用，因此它既可以丢弃用户提供的工具，也可以丢弃由 harness 中间件添加的工具。有关完整示例，请参阅 在不使用默认文件系统工具的情况下运行。

frozenset[type[AgentMiddleware] | str]

从 Deep Agents 技术栈 中剥离特定的中间件类。接受中间件类或字符串名称。

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

将中间件追加到该配置文件适用的每个技术栈。有关内置顺序，请参阅 Deep Agents 技术栈。

GeneralPurposeSubagentProfile

禁用、重命名或重新提示通用子智能体。当此字段的 system_prompt 与 base_system_prompt 一并设置时，通用子智能体专属的提示词获胜——参见 通用子智能体提示词。

NOTE

调用者提供的 system_prompt= 始终位于组装后提示词的开头，而 system_prompt_suffix 始终位于末尾——无论选择哪个模型都是如此。同样的叠加规则也适用于子智能体：每个子智能体都会针对自己的模型重新运行配置文件解析。有关自定义指令和子智能体提示词行为，请参阅 系统提示词。

WARNING

要在没有 task 工具的情况下运行智能体，请参阅 在不使用子智能体的情况下运行——设置 general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)，并通过 subagents= 不传入任何同步子智能体。只有当至少存在一个同步子智能体时，才会附加 SubAgentMiddleware（以及 task 工具），因此这种配置会干净地将其省略。异步子智能体不受影响。

在 excluded_middleware 中列出 FilesystemMiddleware、SubAgentMiddleware 或内部权限中间件会引发 ValueError——它们是 Deep Agents 技术栈 中必需的脚手架。要在不移除中间件的情况下对模型隐藏它们的工具，请改用 excluded_tools——参见 在不使用默认文件系统工具的情况下运行。

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

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

在创建智能体之前注册配置文件。传入模型字符串或你自己构建的模型对象；有关示例，请参阅 配置模型参数。在两种情况下 harness 配置文件都会生效。

服务商配置文件仅在你传入字符串时提供构建设置。

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

当你传入模型对象时，harness 会使用该对象报告的 provider 和 identifier 来查找其配置文件。

  1. 精确的 provider:identifier 匹配
  2. 仅 identifier（仅当 identifier 已包含 : 时）
  3. 所报告 provider 的默认值，或者如果 provider 未知，则为 identifier 前缀的默认值

两个精确候选都优先于 provider 默认值。

注册键

配置文件注册使用以下键：

  • 服务商级别——像 "openai" 这样的裸 provider 名称会应用于来自该服务商的每个模型。
  • 模型级别——像 "openai:gpt-6-astra" 这样完全限定的 provider:model 键只应用于该特定模型。

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

只有第一个冒号用于分隔 provider 和模型标识符。对于假想的键 my_provider:my-model:tag，provider 是 my_provider，完整的模型标识符是 my-model:tag。任何额外的冒号都是模型标识符的一部分。

例如，为一个假想服务商的所有模型排除某个工具，然后为其中一个模型自定义提示词后缀：

python
from deepagents import HarnessProfile, register_harness_profile

# Set defaults for a hypothetical provider.
register_harness_profile(
    "my_provider",
    HarnessProfile(
        excluded_tools=frozenset({"execute"}),
        system_prompt_suffix="Respond in under 500 words.",
    ),
)

# Override the prompt suffix for one model; inherit the excluded tool.
register_harness_profile(
    "my_provider:my-model:tag",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)

使用模型特定注册的智能体会排除 execute，并获得 100 词的后缀。来自 my_provider 的其他模型会排除 execute，并获得 500 词的后缀。

在现有键下重新注册会将新配置文件合并到先前的配置文件之上；而不是替换它。这还让你可以通过在其键下注册来自定义内置配置文件。有关逐字段规则，请参阅 合并语义。

继续该示例，为同一个模型再排除一个工具：

python
register_harness_profile(
    "my_provider:my-model:tag",
    HarnessProfile(excluded_tools=frozenset({"grep"})),
)

此后使用该模型创建的智能体会同时排除 execute 和 grep，并保留 100 词的后缀。其他模型保持服务商默认值。

NOTE

没有可以匹配每个服务商的通配符键。要在所有地方应用相同的覆盖——例如，无论选择哪个模型都丢弃 SummarizationMiddleware——请在你使用的每个服务商键下注册该配置文件。配置文件旨在用于依赖于所选模型的调整。无论模型如何都应生效的全局调整，应在 create_deep_agent 调用处进行。

合并语义

字段合并行为
base_system_prompt、system_prompt_suffix设置时新值获胜；否则继承
tool_description_overrides映射按键合并；在共享键上新值获胜
excluded_tools、excluded_middleware集合并集
extra_middleware按具体类型合并：新实例在其位置替换现有实例，新类型则追加
general_purpose_subagent按字段合并（未设置的字段继承）
init_kwargs（provider）字典按键合并；在共享键上新值获胜
pre_init（provider）可调用对象串联：先运行现有的，再运行新的
init_kwargs_factory（provider）工厂串联，其输出在每次模型构建时合并

服务商配置文件

当你将 provider:model 字符串传给 create_deep_agent 时，ProviderProfile 提供模型构建设置。对于下面的假想服务商，为其所有模型设置默认值，然后覆盖其中一个模型的 temperature：

python
from deepagents import ProviderProfile, register_provider_profile

register_provider_profile(
    "my_provider",
    ProviderProfile(init_kwargs={"temperature": 0.7, "timeout": 30}),
)
register_provider_profile(
    "my_provider:my-model:tag",
    ProviderProfile(init_kwargs={"temperature": 0}),
)

构建 my_provider:my-model:tag 时使用 temperature=0 并继承 timeout=30。来自 my_provider 的其他模型使用 temperature=0.7 和 timeout=30。

要增加此模型的 timeout，请在其键下再次注册：

python
register_provider_profile(
    "my_provider:my-model:tag",
    ProviderProfile(init_kwargs={"timeout": 60}),
)

将来构建此模型时使用 temperature=0 和 timeout=60。这些注册不会更改现有的模型对象。

Mapping[str, Any]

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

Callable[[str], None]

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

Callable[[], dict[str, Any]]

从运行时状态派生的 kwargs（例如从环境变量中获取的 headers）。

从配置文件加载 profile

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

register_harness_profile 接受任一类型，因此由配置驱动的调用者无需手动转换步骤：

yaml
# 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
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。

将 profile 作为插件发布

可分发配置文件可以通过 importlib.metadata 入口点自行注册，而无需调用者手动运行 register_*_profile。加载顺序为 先内置项，然后是入口点插件，然后是用户代码中任何直接的 register_*_profile 调用；这三条路径都汇入同一种追加式注册，因此在同一个键下，较晚的注册会叠加在较早的注册之上。

在该分发包自己的 pyproject.toml 中，在相应的分组下声明一个入口点：

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 时它会执行注册：

python
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}),
    )

相关

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可