以编程方式使用文档

Harness 配置文件 允许您打包配置，Deep Agents 在选择给定提供者或特定模型时会应用这些配置：系统提示词调整、工具描述覆盖、排除的工具或中间件、额外的中间件，以及通用子代理编辑。这是调整 Harness 对特定模型行为的主要方式，而无需更改您的 createDeepAgent 调用站点。使用 HarnessProfileOptions 来构建配置文件；使用 parseHarnessProfileConfig 当 loading or saving YAML/JSON files时。Deep Agents 附带了 OpenAI 和 Anthropic (Claude) 模型的内置 Harness 配置文件。

Harness 配置文件

Harness 配置文件描述了聊天模型构造后 createDeepAgent 应用的提示词组装、工具可见性、中间件和默认子代理调整：

registerHarnessProfile("openai:gpt-5.5", {
  systemPromptSuffix: "Respond in under 100 words.",
  excludedTools: ["execute"],
  excludedMiddleware: ["SummarizationMiddleware"],
  generalPurposeSubagent: { enabled: false },
});

替换基础 Deep Agents 系统提示词 (CUSTOM in 提示词组装).

向组装后的基础提示词追加文本 (SUFFIX in 提示词组装)；应用于主代理、声明式子代理以及自动添加的通用子代理。

"> 按工具名称覆盖各个工具的描述。

从工具集中移除特定的测试框架级工具。按工具名称匹配，作为注入后过滤器应用，因此能捕获用户提供的和中间件提供的工具。

从组装的中间件堆栈中剥离特定的中间件。按各中间件的 .name 属性进行匹配。不可包含必需的脚手架名称 (FilesystemMiddleware, SubAgentMiddleware).

AgentMiddleware[])"> 在用户中间件之后追加到堆栈的附加中间件。可以是静态数组或无参数工厂函数，为每个代理构造返回新鲜实例。

禁用、重命名或重新设置通用子代理 (enabled, description, systemPrompt).

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

当您传递预配置的聊天模型实例而不是 provider:model 字符串时，harness 会从实例中合成为规范 provider:identifier key 并按以下顺序查找：

1. 精确 provider:identifier 匹配 2. 仅限标识符（仅当标识符已包含 :) 3. 仅提供商回退

注册密钥

两种 profile 类型使用相同的密钥格式：

  • Provider-level — 一个裸提供商名称如 "openai" 适用于该提供商的所有模型。
  • Model-level — 一个完全限定的 provider:model key 如 "openai:gpt-5.5" 仅适用于该特定模型。

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

使用现有密钥重新注册会将新 profile 合并到先前 profile 之上——不会替换它。参见 合并语义 了解逐字段规则。

合并语义

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

提供者配置

提供者配置（用于控制模型构造 kwargs，如 temperature）是 Python 独有功能，在 TypeScript SDK 中不可用。

从配置文件加载配置

For YAML/JSON-backed workflows, use parseHarnessProfileConfig。它从具有驼峰命名键的普通对象验证并构建 HarnessProfile 。仅运行时状态 — extraMiddleware instances — cannot be represented in JSON/YAML and must be set programmatically.

# profile.yaml
baseSystemPrompt: You are helpful.
systemPromptSuffix: Respond briefly.
excludedTools:
  - execute
  - grep
excludedMiddleware:
  - SummarizationMiddleware
generalPurposeSubagent:
  enabled: false
const raw = YAML.parse(readFileSync("profile.yaml", "utf-8"));
registerHarnessProfile("openai", parseHarnessProfileConfig(raw));

To serialize a profile back to JSON/YAML, use serializeProfile:

const data = serializeProfile(profile); // JSON-compatible object

包含非空 extraMiddleware 的配置无法序列化 — serializeProfile 如果存在中间件实例则抛出异常。

将配置作为插件发布

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

相关