跳到主要内容

文档索引

在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt

在进一步探索之前，请使用此文件发现所有可用页面。

Harness 和提供商配置仅适用于 Python，且需要 deepagents>=0.5.4。它们属于公开测试版 API，未来版本可能会更新。
Harness 配置允许您打包 Deep Agents 在选择给定提供商或特定模型时所应用的相关配置：系统提示词微调、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用的子智能体编辑。这是在不更改 create_deep_agent 调用点的情况下，调整特定模型下 harness 行为的主要方式。在 Python 中构建配置时，请使用 HarnessProfile；在 加载或保存 YAML/JSON 文件 时，请使用 HarnessProfileConfig。Deep Agents 为 OpenAI 和 Anthropic (Claude) 模型提供了内置的 Harness 配置。 提供商配置是一个针对模型构建关键字参数（kwargs）的辅助 API，它不影响 harness。大多数调用者不需要使用它；当您希望在使用提供商选择时默认包含 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
字符串
替换基础 Deep Agents 系统提示词（提示词组装中的 CUSTOM）。
​
system_prompt_suffix
字符串
在组装好的基础提示词后追加文本（提示词组装中的 SUFFIX）；适用于主智能体、声明式子智能体以及自动添加的通用子智能体。
​
tool_description_overrides
Mapping[str, str]
根据工具名称，覆盖各个工具的描述。
​
excluded_tools
frozenset[str]
从工具集中移除特定的 harness 级别工具。
​
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 字符串时，harness 会从实例中合成规范的 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 声明了 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}),
    )
  • Harness — harness 功能概述
  • 模型 — 配置模型提供商和参数
  • 自定义 — 完整的 create_deep_agent 配置面
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页面 或 提交问题。
© . This site is unofficial and not affiliated with LangChain, Inc.