配置文件体系 (Profiles) [Beta]

按模型或提供商打包声明式调优，涵盖提示词、工具、中间件与子智能体设置

不同的基础模型在工具调用习惯、人设遵循度以及对系统提示词格式的偏好上存在显著差异。 配置文件（Profiles）允许你将针对特定模型或特定提供商的微调配置打包起来，当创建智能体并选用该模型时自动激活，避免在业务代码中充斥大量分散的 if-else 模型分支判断。

框架配置文件 (Harness profiles)

HarnessProfile 允许你声明性地调整智能体运行框架：

• 追加或替换模型特定的系统提示词后缀（system_prompt_suffix）。
• 隐藏或排除某些内置工具（excluded_tools）。
• 注册特定的中间件或自定义通用子智能体的人设。

import { registerHarnessProfile } from "deepagents";

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

注册键格式 (Registration keys)

你可以针对不同粒度注册 Profile，系统支持优雅的多层并存：

• 提供商级别：如 "openai" 或 "anthropic"，对来自该提供商的所有模型统一生效。
• 具体模型级别：如 "openai:gpt-5.5" 或 "anthropic:claude-sonnet-4-6"，仅对该指定模型生效。

合并语义 (Merge semantics)

当针对某个具体模型既匹配了提供商级 Profile，又匹配了模型级 Profile 时，Deep Agents 采用深度优先合并规则： 模型级配置字段优先覆盖提供商级字段；数组和集合字段（如 excluded_tools）执行并集去重合并。

提供商配置文件 (Provider profiles)

ProviderProfile 专注于模型实例化阶段的底层参数打包，例如为特定提供商自动配置默认超时、重试策略或专属请求头。

从配置文件加载 Profile (Load from config)

除了在代码中调用 API 注册外，你还可以将 Profile 声明为标准的 YAML 配置文件：

import { registerHarnessProfile } from "deepagents";

// Set defaults for a hypothetical provider.
registerHarnessProfile("my_provider", {
  excludedTools: ["execute"],
  systemPromptSuffix: "Respond in under 500 words.",
});

// Override the prompt suffix for one model; inherit the excluded tool.
registerHarnessProfile("my_provider:my-model", {
  systemPromptSuffix: "Respond in under 100 words.",
});

将 Profile 打包为分发插件 (Ship as plugin)

团队可以将调优成熟的 Profile 封装为 NPM/Python 独立包，供多个业务工程一键安装并声明式复用。

相关参考

• 模型体系 (Models)：受支持的模型列表与推荐配置。
• 中间件体系 (Middleware)：中间件装配顺序。

registerHarnessProfile("my_provider:my-model", {
  excludedTools: ["grep"],
});

Agents created afterward with this model exclude both execute and grep and retain the 100-word suffix. Other models keep the provider defaults.

NOTE

There is no wildcard key that matches every provider. To apply the same overrides everywhere—say, dropping SummarizationMiddleware regardless of which model is selected—register the profile under each provider key you use. Profiles are intended for adjustments that depend on the model being selected. Global adjustments that should apply regardless of model should be made on the createDeepAgent call site.

Merge semantics

Field	Merge behavior
baseSystemPrompt, systemPromptSuffix	New value wins when set; otherwise inherits
toolDescriptionOverrides	Mappings merge per key; new value wins on a shared key
excludedTools, excludedMiddleware	Set union
extraMiddleware	Merged by name: new instance replaces existing at its position, novel entries append
generalPurposeSubagent	Merged field-wise (unset fields inherit)

Provider profiles

Provider profiles (for controlling settings used to create a model, such as temperature) are a Python-only feature and are not available in the TypeScript SDK.

Load profiles from config files

For YAML/JSON-backed workflows, use parseHarnessProfileConfig. It validates and builds a HarnessProfile from a plain object with camelCase keys. Runtime-only state such as 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

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));

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

import { serializeProfile } from "deepagents";

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

Profiles with non-empty extraMiddleware cannot be serialized; serializeProfile throws if middleware instances are present.

Ship a profile as a plugin

The plugin registration system (via package entry points) is a Python-only feature. In TypeScript, call registerHarnessProfile directly at application startup or in your package's initialization code.

Related

• Harness Overview—harness capabilities overview

• Models—configure model providers and parameters

• Customization—full createDeepAgent configuration surface

---

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.