配置文件

运行环境配置文件 让你能够打包 Deep Agents 在选定某个特定提供商或模型时应用的配置：系统提示词调整、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用子智能体编辑。它们是调整运行环境对特定模型行为的主要方式，无需更改你的 createDeepAgent 调用点。使用 HarnessProfileOptions 来构建配置文件；当从配置文件加载或保存 YAML/JSON 文件时使用 parseHarnessProfileConfig。Deep Agents 内置了适用于 OpenAI 和 Anthropic (Claude) 模型的运行环境配置文件。

提供商配置文件（用于控制模型构建关键字参数）和插件注册系统是 Python 专属功能。TypeScript SDK 仅支持运行环境配置文件。

运行环境配置文件

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

import { registerHarnessProfile } from "deepagents";

registerHarnessProfile("openai:gpt-5.5", {
  systemPromptSuffix: "请用不超过100个字回应。",
  excludedTools: ["execute"],
  excludedMiddleware: ["SummarizationMiddleware"],
  generalPurposeSubagent: { enabled: false },
});

string

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

string

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

Record<string, string>

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

string[]

从工具集中移除特定的运行环境级工具。通过工具名称匹配，作为注入后过滤器应用，因此它可以捕获用户提供的和中间件提供的工具。

string[]

从组装好的栈中剥离特定的中间件。根据每个中间件的 .name 属性进行匹配。不能包含必需的脚手架名称（FilesystemMiddleware、SubAgentMiddleware）。

AgentMiddleware[] | (() => AgentMiddleware[])

在用户中间件之后追加到栈中的额外中间件。可以是一个静态数组或一个零参数工厂函数，该函数为每次智能体构造返回新实例。

GeneralPurposeSubagentConfig

禁用、重命名或重新提示通用子智能体（enabled、description、systemPrompt）。

调用者提供的 systemPrompt 始终位于组装好的提示词的最前面，而 systemPromptSuffix 始终位于最后——无论选择哪个模型。同样的覆盖规则适用于子智能体：每个子智能体根据其自己的模型重新运行配置文件解析。有关每种情况（主智能体、子智能体和通用子智能体）的详细分解，请参见系统提示词。

在 excludedMiddleware 中列出 FilesystemMiddleware 或 SubAgentMiddleware 会在构造时抛出异常——它们是必需的脚手架。若要在不移除中间件的情况下对模型隐藏其工具，请改用 excludedTools。

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

当你传递一个预配置的聊天模型实例而不是 provider:model 字符串时，运行环境会从该实例合成规范的 provider:identifier 键，并按以下顺序查找：

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

注册键

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

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

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

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

合并语义

字段	合并行为
`baseSystemPrompt`, `systemPromptSuffix`	新值设置时胜出；否则继承
`toolDescriptionOverrides`	映射按键合并；共享键上新值胜出
`excludedTools`, `excludedMiddleware`	集合并集
`extraMiddleware`	按名称合并：新实例替换其位置的现有实例，新条目追加
`generalPurposeSubagent`	按字段合并（未设置字段继承）

提供商配置文件

提供商配置文件（用于控制 temperature 等模型构建关键字参数）是 Python 专属功能，在 TypeScript SDK 中不可用。

从配置文件加载配置文件

对于基于 YAML/JSON 的工作流，请使用 parseHarnessProfileConfig。它验证并从具有驼峰式键的普通对象构建 HarnessProfile。运行时专用的状态（如 extraMiddleware 实例）无法在 JSON/YAML 中表示，必须通过编程方式设置。

# profile.yaml
baseSystemPrompt: You are helpful.
systemPromptSuffix: Respond briefly.
excludedTools:
  - execute
  - grep
excludedMiddleware:
  - SummarizationMiddleware
generalPurposeSubagent:
  enabled: false

import { readFileSync } from "fs";
import YAML from "yaml";
import { parseHarnessProfileConfig, registerHarnessProfile } from "deepagents";

const raw = YAML.parse(readFileSync("profile.yaml", "utf-8"));
registerHarnessProfile("openai", parseHarnessProfileConfig(raw));

要将配置文件序列化回 JSON/YAML，请使用 serializeProfile：

import { serializeProfile } from "deepagents";

const data = serializeProfile(profile); // JSON 兼容的对象

具有非空 extraMiddleware 的配置文件无法序列化；如果存在中间件实例，serializeProfile 会抛出异常。

将配置文件作为插件发布

插件注册系统（通过包入口点）是 Python 专属功能。在 TypeScript 中，请在应用启动时或在你的包初始化代码中直接调用 registerHarnessProfile。

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

运行环境配置文件

注册键

合并语义

提供商配置文件

从配置文件加载配置文件

将配置文件作为插件发布

相关

​运行环境配置文件

​注册键

​合并语义

​提供商配置文件

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

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

​相关

运行环境配置文件

注册键

合并语义

提供商配置文件

从配置文件加载配置文件

将配置文件作为插件发布

相关