DeepAgents Profiles 完整学习指南：从概念到实战

目录

[1. Profiles 解决什么问题](#1. Profiles 解决什么问题)

[2. 两种 Profile：一眼看懂区别](#2. 两种 Profile：一眼看懂区别)

[3. Harness Profile 详解](#3. Harness Profile 详解)

[3.1 什么是 Harness Profile](#3.1 什么是 Harness Profile)

[3.2 核心类：HarnessProfile](#3.2 核心类：HarnessProfile)

[3.3 参数逐个讲](#3.3 参数逐个讲)

[3.3.1 base_system_prompt --- 替换基座提示词](#3.3.1 base_system_prompt — 替换基座提示词)

[3.3.2 system_prompt_suffix --- 追加后缀提示（最常用）](#3.3.2 system_prompt_suffix — 追加后缀提示（最常用）)

[3.3.3 tool_description_overrides --- 覆写工具描述](#3.3.3 tool_description_overrides — 覆写工具描述)

[3.3.4 excluded_tools --- 移除不需要的工具](#3.3.4 excluded_tools — 移除不需要的工具)

[3.3.5 excluded_middleware --- 移除中间件](#3.3.5 excluded_middleware — 移除中间件)

[3.3.6 extra_middleware --- 追加额外中间件](#3.3.6 extra_middleware — 追加额外中间件)

[3.3.7 general_purpose_subagent --- 配置/禁用通用子代理](#3.3.7 general_purpose_subagent — 配置/禁用通用子代理)

[4. Provider Profile 详解](#4. Provider Profile 详解)

[4.1 是什么](#4.1 是什么)

[4.2 三个参数](#4.2 三个参数)

[4.3 小例子：动态 header 注入](#4.3 小例子：动态 header 注入)

[4.4 重要限制](#4.4 重要限制)

[5. 注册键格式：哪个模型匹配哪个 Profile](#5. 注册键格式：哪个模型匹配哪个 Profile)

[5.1 两种键级别](#5.1 两种键级别)

[5.2 注册示例](#5.2 注册示例)

[5.3 查找优先级](#5.3 查找优先级)

[5.4 不支持通配符](#5.4 不支持通配符)

[6. 合并语义：重复注册会发生什么](#6. 合并语义：重复注册会发生什么)

各字段合并规则一览

[7. YAML/JSON 配置文件方式](#7. YAML/JSON 配置文件方式)

[7.1 HarnessProfileConfig --- 可声明的子集](#7.1 HarnessProfileConfig — 可声明的子集)

[7.2 完整示例：用 YAML 配置](#7.2 完整示例：用 YAML 配置)

[7.3 反向导出：从 HarnessProfile 导出为 Config](#7.3 反向导出：从 HarnessProfile 导出为 Config)

[8. 插件式分发：让它自动加载](#8. 插件式分发：让它自动加载)

[8.1 pyproject.toml 配置](#8.1 pyproject.toml 配置)

[8.2 Python 注册函数](#8.2 Python 注册函数)

[8.3 加载顺序](#8.3 加载顺序)

[9. 完整实战示例](#9. 完整实战示例)

[9.1 场景：为 Qwen 模型定制 Agent 行为](#9.1 场景：为 Qwen 模型定制 Agent 行为)

[9.2 场景：模型切换 --- 不同的模型不同的行为](#9.2 场景：模型切换 — 不同的模型不同的行为)

[9.3 场景：YAML 驱动的运维配置](#9.3 场景：YAML 驱动的运维配置)

[10. 常见问题与排查](#10. 常见问题与排查)

[10.1 Profile 没生效？](#10.1 Profile 没生效？)

[10.2 想移除 FilesystemMiddleware 但是报错](#10.2 想移除 FilesystemMiddleware 但是报错)

[10.3 多个 Profile 叠加后行为不符合预期](#10.3 多个 Profile 叠加后行为不符合预期)

[10.4 插件 Entry Point 没有自动加载](#10.4 插件 Entry Point 没有自动加载)

[11. 总结](#11. 总结)

核心概念速查

推荐实践

1. Profiles 解决什么问题

使用 DeepAgents 时，你可能会遇到这些场景：

换了一个模型（比如从 GPT-5.5 换到 Claude），发现 Agent 的行为变了------有些工具它不会用，输出风格也不对。
想全局去掉某些工具（比如 grep），又不想在每个 create_deep_agent() 调用处重复配置。
想让某个模型的回答始终简洁，加后缀提示词，但其他模型不受影响。
需要把配置以 YAML 文件形式分发，让团队或插件自动加载。

Profiles 就是用来解决这些问题的。 它让你可以：

针对不同 provider 或具体模型，预先配置 Deep Agent 的运行时行为（工具、中间件、提示词、子代理），而无需修改每次 create_deep_agent() 的调用代码。

核心思想是 "注册一次，自动应用"------只要传入的模型匹配到某个已注册的 profile，配置就会自动生效。

2. 两种 Profile：一眼看懂区别

DeepAgents 提供两类 Profile，职责完全不同：

维度	Harness Profile	Provider Profile
控制什么	Agent 运行时行为（提示词、工具、中间件）	模型构造参数（temperature、max_tokens 等）
核心类	`HarnessProfile` / `HarnessProfileConfig`	`ProviderProfile`
影响范围	工具集、中间件栈、系统提示词、子代理	`init_chat_model` 的 kwargs
何时生效	任何方式传入的模型（字符串 / 实例）	仅当传入 `"provider:model"` 字符串时
使用频率	高 --- 绝大多数配置都在这里	低 --- 多数人用不到

一句话概括：

Harness Profile = 控制 Agent 怎么干活。

Provider Profile = 控制模型怎么初始化。

3. Harness Profile 详解

3.1 什么是 Harness Profile

"Harness" 在 DeepAgents 中指的是运行 Agent 的底层框架壳 ------它负责组装工具、中间件、提示词，并把模型调用串联起来。Harness Profile 就是对这个壳的预配置打包。

3.2 核心类：`HarnessProfile`

python 复制代码

from deepagents import HarnessProfile

HarnessProfile(
    base_system_prompt=None,            # 完全替换内置的系统提示词
    system_prompt_suffix=None,           # 追加到系统提示词末尾
    tool_description_overrides=None,     # 覆写特定工具的描述
    excluded_tools=None,                 # 移除指定工具
    excluded_middleware=None,            # 移除指定中间件
    extra_middleware=None,               # 追加额外中间件
    general_purpose_subagent=None,       # 配置/禁用通用子代理
)

每个参数都是可选的，未设置的参数不会覆盖默认行为。

3.3 参数逐个讲

3.3.1 `base_system_prompt` --- 替换基座提示词

DeepAgents 内部有一套默认的系统提示词（告诉模型它有哪些工具、怎么使用等）。设置此参数会完全替换它。

python 复制代码

register_harness_profile(
    "openai",
    HarnessProfile(
        base_system_prompt=(
            "You are a Python data analyst. "
            "Always write and execute code to answer questions. "
            "Never guess results --- compute them."
        ),
    ),
)

使用场景： 想完全掌控 Agent 的行为指令时。一般不推荐轻易替换，system_prompt_suffix 更常用。

3.3.2 `system_prompt_suffix` --- 追加后缀提示（最常用）

这是在调用者传入的 system_prompt 后面再追加内容。 调用者传的放在最前面，后缀放在最后面，保证你的全局要求总是最后出现（模型对末尾内容关注度更高）。

python 复制代码

register_harness_profile(
    "openai",
    HarnessProfile(
        system_prompt_suffix="Always respond in Simplified Chinese. Keep answers under 200 words.",
    ),
)

提示词最终组装顺序：

text 复制代码

[调用者传入的 system_prompt]
    ↓
[DeepAgents 内置基座提示词（或 base_system_prompt 替换的版本）]
    ↓
[system_prompt_suffix]    ← 最后，模型最关注的位置

适用场景：

统一输出语言（"用中文回答"）
限制输出长度
添加安全规则
强制行为指令（"必须先读文件再执行"）

3.3.3 `tool_description_overrides` --- 覆写工具描述

按工具名称精确匹配，替换该工具的描述文本。

python 复制代码

register_harness_profile(
    "openai",
    HarnessProfile(
        tool_description_overrides={
            "write_file": (
                "写入文件。注意：你只能写入 /workspace 目录下的文件，"
                "其他路径会被拒绝。写入前请确保目录存在。"
            ),
            "execute": (
                "在隔离沙箱中执行 shell 命令。每次只能执行一条命令。"
                "执行超时时间为 30 秒。"
            ),
        },
    ),
)

适用场景： 某些模型对默认工具描述"理解不好"，通过覆写描述来引导模型正确使用。

3.3.4 `excluded_tools` --- 移除不需要的工具

传入一个工具名称集合，这些工具会被从 Agent 的工具列表中移除。

python 复制代码

register_harness_profile(
    "openai",
    HarnessProfile(
        excluded_tools={"grep", "glob", "edit_file"},
    ),
)

关键理解： excluded_tools 是一个后注入过滤器------它可以移除：

DeepAgents 内置工具
用户通过 tools= 参数传入的自定义工具
中间件添加的工具

常见场景：

只想让 Agent 用 Python 代码而非 grep 搜索 → 去掉 grep，保留 execute
对简单任务限制工具数量，减少模型选择困难
安全限制：去掉 execute 不让模型运行代码

3.3.5 `excluded_middleware` --- 移除中间件

python 复制代码

register_harness_profile(
    "openai",
    HarnessProfile(
        excluded_middleware={"SummarizationMiddleware"},
    ),
)

支持三种匹配方式：

方式	示例	说明
类名字符串	`"SummarizationMiddleware"`	匹配 `AgentMiddleware.name`
中间件类	`SummarizationMiddleware`	精确类型匹配
导入路径	`"my_pkg.middleware:TelemetryMiddleware"`	延迟解析，仅限可信配置

不能移除的中间件（受保护）：

FilesystemMiddleware --- 文件操作的基础
SubAgentMiddleware --- 子代理管理
内部权限中间件

尝试排除它们会抛出 ValueError。如果只是想隐藏这些中间件提供的工具，用 excluded_tools 替代。

注意： 如果要去掉 task 工具（通用子代理），需要同时设置 general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False) 并且不传入任何同步子代理。

3.3.6 `extra_middleware` --- 追加额外中间件

python 复制代码

from my_middleware import LoggingMiddleware, RateLimitMiddleware

register_harness_profile(
    "openai",
    HarnessProfile(
        extra_middleware=[
            LoggingMiddleware(),
            RateLimitMiddleware(max_calls_per_minute=60),
        ],
    ),
)

可以传入：

列表形式： [Middleware1(), Middleware2()]
工厂函数形式： lambda: [Middleware1(), Middleware2()] --- 每次构建 Agent 时延迟创建

3.3.7 `general_purpose_subagent` --- 配置/禁用通用子代理

python 复制代码

from deepagents import GeneralPurposeSubagentProfile

register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        general_purpose_subagent=GeneralPurposeSubagentProfile(
            enabled=False,                          # 完全禁用通用子代理
        ),
    ),
)

# 或者只改名字和提示词
register_harness_profile(
    "openai:gpt-4o-mini",
    HarnessProfile(
        general_purpose_subagent=GeneralPurposeSubagentProfile(
            name="helper",                          # 重命名
            description="A helper for small tasks", # 修改描述
            system_prompt="You complete small, focused tasks quickly.",
        ),
    ),
)

适用场景：

简单任务不需要子代理 → 禁用，减少模型决策复杂度
想让子代理有更明确的定位 → 重命名并定制提示词

4. Provider Profile 详解

4.1 是什么

Provider Profile 是 Harness Profile 的窄化伴生 API ，只影响模型构造阶段的 init_chat_model() 参数。

python 复制代码

from deepagents import ProviderProfile, register_provider_profile

register_provider_profile(
    "openai",
    ProviderProfile(
        init_kwargs={"temperature": 0},
    ),
)

4.2 三个参数

参数	类型	作用
`init_kwargs`	`dict`	静态参数，直接转发给 `init_chat_model()`
`pre_init`	`Callable[[str], None]`	构造模型前执行的副作用（如验证凭据）
`init_kwargs_factory`	`Callable[[], dict]`	动态生成 kwargs（如从环境变量取请求头）

python 复制代码

import os
from deepagents import ProviderProfile, register_provider_profile

def build_kwargs():
    """从环境变量动态构建 kwargs"""
    extra = {}
    if os.getenv("AZURE_HEADER"):
        extra["default_headers"] = {"X-Custom": os.getenv("AZURE_HEADER")}
    return extra

register_provider_profile(
    "openai",
    ProviderProfile(
        init_kwargs={"temperature": 0, "max_tokens": 4096},
        init_kwargs_factory=build_kwargs,
    ),
)

每次创建 Agent 时，init_kwargs_factory 都会被调用，生成的 kwargs 会与 init_kwargs 合并。

4.4 重要限制

Provider Profile 只在传入 "provider:model" 字符串时才生效。

python 复制代码

# ✅ Provider Profile 会生效
agent = create_deep_agent(model="openai:gpt-5.5")

# ❌ Provider Profile 不会生效（传的是已初始化的模型实例）
from langchain.chat_models import init_chat_model
model = init_chat_model("openai:gpt-5.5", temperature=0)
agent = create_deep_agent(model=model)

5. 注册键格式：哪个模型匹配哪个 Profile

5.1 两种键级别

text 复制代码

Provider 级： "openai"          → 匹配该 provider 下的所有模型
Model 级：    "openai:gpt-5.5"  → 只匹配这一个具体模型

5.2 注册示例

python 复制代码

from deepagents import HarnessProfile, register_harness_profile

# ① 对 OpenAI 所有模型生效
register_harness_profile(
    "openai",
    HarnessProfile(
        system_prompt_suffix="Use Chinese to respond.",
    ),
)

# ② 仅对 GPT-5.5 生效（会继承 ① 的配置并与自身合并）
register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        system_prompt_suffix="Use Chinese. Be concise --- under 100 words.",
        excluded_tools={"grep"},
    ),
)

5.3 查找优先级

当传入模型 "openai:gpt-5.5" 时，harness 按以下顺序查找并合并：

text 复制代码

1. 精确匹配 "openai:gpt-5.5"  →  找到 ②
2. Provider 回退 "openai"     →  找到 ①

合并结果：① 作为基础 + ② 的字段覆盖（未设置的字段继承 ①）

如果传入的是已初始化的模型实例（非字符串），harness 会从实例中提取 provider:identifier，按同样逻辑查找。

5.4 不支持通配符

不能写 "*" 匹配所有 provider。要对所有 provider 做相同配置，需要逐个注册。全局性调整应直接在 create_deep_agent() 调用处完成。

6. 合并语义：重复注册会发生什么

对同一个键 多次注册会合并而非替换：

python 复制代码

# 第一次注册
register_harness_profile(
    "openai",
    HarnessProfile(
        system_prompt_suffix="Part A",
        excluded_tools={"grep"},
    ),
)

# 第二次注册（同一个键）
register_harness_profile(
    "openai",
    HarnessProfile(
        system_prompt_suffix="Part B",        # 覆盖！
        excluded_tools={"glob"},              # 合并取并集！
    ),
)

# 最终结果：
# system_prompt_suffix = "Part B"            ← 后来者覆盖
# excluded_tools = {"grep", "glob"}          ← 取并集

各字段合并规则一览

字段	合并行为
`base_system_prompt`	新值覆盖旧值
`system_prompt_suffix`	新值覆盖旧值
`tool_description_overrides`	按 key 合并，共享 key 上新值覆盖
`excluded_tools`	取并集
`excluded_middleware`	取并集
`extra_middleware`	按名称合并：同名替换，新名称追加
`general_purpose_subagent`	字段级合并（未设置的字段继承）
`init_kwargs` (Provider)	按 key 合并，共享 key 上新值覆盖
`pre_init` (Provider)	链式执行（先执行旧的，再执行新的）
`init_kwargs_factory` (Provider)	链式执行，输出合并

核心直觉： 标量覆盖，集合合并，可调用链式执行。

7. YAML/JSON 配置文件方式

除了在 Python 代码中直接用 HarnessProfile，还可以用 YAML 或 JSON 文件声明配置，适合团队协作和运维管理。

7.1 `HarnessProfileConfig` --- 可声明的子集

python 复制代码

from deepagents import HarnessProfileConfig

HarnessProfileConfig 覆盖 HarnessProfile 的可声明部分：

提示词文本（base_system_prompt、system_prompt_suffix）
工具描述覆写
排除的工具（名称字符串）
排除的中间件（名称字符串 / 导入路径）
通用子代理配置

不能声明的内容： 中间件实例、工厂函数、中间件类形式------这些属于运行时状态，只在 HarnessProfile 中存在。

7.2 完整示例：用 YAML 配置

YAML 文件 openai_profile.yaml：

yaml 复制代码

base_system_prompt: You are a helpful coding assistant.
system_prompt_suffix: |
  Important rules:
  1. Always write tests before code.
  2. Use Chinese for all explanations.
  3. Keep code examples under 50 lines.

tool_description_overrides:
  write_file: "创建或覆写文件。必须先确认目录存在。"

excluded_tools:
  - execute     # 不允许运行代码
  - grep        # 不允许搜索

excluded_middleware:
  - SummarizationMiddleware
  - my_plugins.telemetry:TelemetryMiddleware

general_purpose_subagent:
  enabled: true
  name: "helper"

加载 YAML 并注册：

python 复制代码

import yaml
from deepagents import HarnessProfileConfig, register_harness_profile

with open("openai_profile.yaml", "r", encoding="utf-8") as f:
    config = HarnessProfileConfig.from_dict(yaml.safe_load(f))

register_harness_profile("openai", config)

7.3 反向导出：从 HarnessProfile 导出为 Config

python 复制代码

from deepagents import HarnessProfile, HarnessProfileConfig

profile = HarnessProfile(
    system_prompt_suffix="Be concise.",
    excluded_tools={"grep"},
)

# 导出为可序列化的 config
config = HarnessProfileConfig.from_harness_profile(profile)
dict_data = config.to_dict()      # 可写入 YAML/JSON

限制： 如果 profile 中有 extra_middleware 实例，或中间件类定义在 __main__ 中，导出会抛出 ValueError。

8. 插件式分发：让它自动加载

如果你在开发一个第三方包（比如公司内部的 DeepAgents 配置包），可以通过 Python 的 entry points 机制自动注册 Profiles，用户安装你的包后无需任何手动注册代码。

8.1 pyproject.toml 配置

toml 复制代码

[project.entry-points."deepagents.harness_profiles"]
my_company = "my_company.deepagent_config:register_harness"

[project.entry-points."deepagents.provider_profiles"]
my_company = "my_company.deepagent_config:register_provider"

8.2 Python 注册函数

python 复制代码

# my_company/deepagent_config.py
from deepagents import (
    HarnessProfile,
    ProviderProfile,
    register_harness_profile,
    register_provider_profile,
)

def register_harness() -> None:
    """此函数会在 deepagents.profiles 被导入时自动调用"""
    register_harness_profile(
        "my_company",
        HarnessProfile(
            system_prompt_suffix="Always follow company code review guidelines.",
            excluded_tools={"execute"},
        ),
    )

def register_provider() -> None:
    register_provider_profile(
        "my_company",
        ProviderProfile(
            init_kwargs={"temperature": 0.1, "max_tokens": 8192},
        ),
    )

8.3 加载顺序

text 复制代码

1. DeepAgents 内置 profiles  ← 最先加载
2. Entry-point 插件          ← 自动发现已安装的包
3. 用户代码中的 register_*   ← 你的显式调用，最后叠加

三种路径汇入同一个增量注册机制，后注册的在同键上叠加。

9. 完整实战示例

9.1 场景：为 Qwen 模型定制 Agent 行为

python 复制代码

import os
from deepagents import (
    GeneralPurposeSubagentProfile,
    HarnessProfile,
    ProviderProfile,
    create_deep_agent,
    register_harness_profile,
    register_provider_profile,
)

# ── 步骤 1：注册 Provider Profile（模型初始化参数） ──
register_provider_profile(
    "openai",
    ProviderProfile(
        init_kwargs={"temperature": 0},
    ),
)

# ── 步骤 2：注册 Harness Profile（Agent 运行时行为） ──
register_harness_profile(
    "openai",
    HarnessProfile(
        system_prompt_suffix=(
            "请始终使用简体中文回答。"
            "在执行任何数据分析任务前，先读取相关文件。"
            "所有计算结果必须通过实际执行代码获得，不得猜测。"
        ),
        excluded_tools={"grep", "glob"},        # 只用 Python 代码做搜索
        tool_description_overrides={
            "execute": (
                "在 Python 沙箱中执行代码。"
                "每次调用只能包含一个完整的代码块。"
                "执行前必须确保所有依赖已安装。"
            ),
        },
    ),
)

# ── 步骤 3：对特定模型做微调（会与上一条合并） ──
register_harness_profile(
    "openai:qwen-plus",
    HarnessProfile(
        system_prompt_suffix=(
            "You are running on Alibaba DashScope via OpenAI-compatible API. "
            "Use Chinese. Keep responses under 500 words."
        ),
        general_purpose_subagent=GeneralPurposeSubagentProfile(
            enabled=True,
            name="qwen_worker",
            description="用于处理独立小任务的子代理",
        ),
    ),
)

# ── 步骤 4：创建 Agent（指定模型字符串即可自动应用 Profile） ──
agent = create_deep_agent(
    model="openai:qwen-plus",       # ← 传字符串，Profile 自动生效
    system_prompt="你是一个数据分析助手。",
    # 无需手动传 tools= 或 middleware=，Profile 已经处理好了
)

9.2 场景：模型切换 --- 不同的模型不同的行为

python 复制代码

# Claude 模型：专业代码审查
register_harness_profile(
    "anthropic:claude-opus-4-8",
    HarnessProfile(
        system_prompt_suffix="You are a senior code reviewer. Focus on correctness and security.",
        excluded_tools={"execute"},  # 审查不需要执行代码
    ),
)

# GPT 模型：快速原型开发
register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(
        system_prompt_suffix="Focus on rapid prototyping. Prefer writing runnable code over lengthy explanations.",
        general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=True),
    ),
)

# 现在只需改变 model 字符串，行为会自动切换：
code_reviewer = create_deep_agent(model="anthropic:claude-opus-4-8")
prototyper    = create_deep_agent(model="openai:gpt-5.5")

9.3 场景：YAML 驱动的运维配置

生产环境中，运维团队不需要改 Python 代码，改 YAML 即可：

python 复制代码

# app.py --- 应用代码，一次性写完
import yaml
from pathlib import Path
from deepagents import HarnessProfileConfig, register_harness_profile, create_deep_agent

# 加载所有 profile 配置
config_dir = Path("config/profiles")
for yaml_file in config_dir.glob("*.yaml"):
    provider_name = yaml_file.stem  # 文件名 = provider 名
    with open(yaml_file) as f:
        config = HarnessProfileConfig.from_dict(yaml.safe_load(f))
    register_harness_profile(provider_name, config)

# 之后正常使用
agent = create_deep_agent(model="openai:qwen-plus")

对应的 config/profiles/openai.yaml：

yaml 复制代码

system_prompt_suffix: "用中文回答，不超过 300 字。"
excluded_tools:
  - execute
general_purpose_subagent:
  enabled: false

10. 常见问题与排查

10.1 Profile 没生效？

常见原因：

问题	解决
传的是模型实例而非字符串	Provider Profile 仅对 `"provider:model"` 字符串生效；Harness Profile 两者都生效
注册发生在 `create_deep_agent` 之后	注册必须在创建 Agent 之前
键名拼写错误	provider 名称必须精确匹配（区分大小写）
环境变量挡住	`init_chat_model()` 的默认参数可能覆盖 Provider Profile

排查方法：

python 复制代码

from deepagents.profiles import get_harness_profile

# 检查已注册的 profile
profile = get_harness_profile("openai:qwen-plus")
print(profile)

10.2 想移除 FilesystemMiddleware 但是报错

受保护的中间件不能排除。换用 excluded_tools 来隐藏它们提供的工具：

python 复制代码

# ❌ 会报 ValueError
HarnessProfile(excluded_middleware={"FilesystemMiddleware"})

# ✅ 正确做法
HarnessProfile(excluded_tools={"write_file", "read_file", "edit_file", "ls", "glob", "grep"})

10.3 多个 Profile 叠加后行为不符合预期

记住合并规则：标量覆盖，集合合并。 如果先后注册了同一个键：

python 复制代码

# 第一个
register_harness_profile("openai", HarnessProfile(excluded_tools={"grep"}))
# 第二个
register_harness_profile("openai", HarnessProfile(excluded_tools={"grep"}))  # 还是 {"grep"}，没变化

如果想让后来的完全替换，需要直接修改前面注册时的 profile，或改用完全限定键（"openai:xxx"）而非 provider 级键。

10.4 插件 Entry Point 没有自动加载

确保：

pyproject.toml 中的 entry point 组名是 deepagents.harness_profiles / deepagents.provider_profiles（注意下划线）
目标函数是零参数可调用对象
包已安装（pip install -e . 开发模式安装）
导入 deepagents.profiles 触发了加载

11. 总结

核心概念速查

text 复制代码

┌──────────────────────────────────────────────────────┐
│                  DeepAgents Profiles                  │
├─────────────────────┬────────────────────────────────┤
│   Harness Profile   │      Provider Profile          │
│   控制 Agent 行为    │      控制模型初始化             │
├─────────────────────┼────────────────────────────────┤
│ • 系统提示词覆写     │ • temperature / max_tokens     │
│ • 工具增删          │ • 自定义 headers               │
│ • 中间件组合         │ • 凭据验证                     │
│ • 子代理配置         │ • 动态 kwargs                  │
├─────────────────────┴────────────────────────────────┤
│  注册方式：register_harness_profile(键, profile)      │
│  注册方式：register_provider_profile(键, profile)     │
│  配置方式：Python 代码 或 YAML/JSON 文件              │
│  分发方式：Entry Points 自动发现                      │
│  合并方式：标量覆盖，集合取并集，可调用链式执行        │
└──────────────────────────────────────────────────────┘

DeepAgents Profiles 完整学习指南：从概念到实战

1. Profiles 解决什么问题

2. 两种 Profile：一眼看懂区别

3. Harness Profile 详解

3.1 什么是 Harness Profile

3.2 核心类：HarnessProfile

3.3 参数逐个讲

3.3.1 base_system_prompt --- 替换基座提示词

3.3.2 system_prompt_suffix --- 追加后缀提示（最常用）

3.3.3 tool_description_overrides --- 覆写工具描述

3.3.4 excluded_tools --- 移除不需要的工具

3.3.5 excluded_middleware --- 移除中间件

3.3.6 extra_middleware --- 追加额外中间件

3.3.7 general_purpose_subagent --- 配置/禁用通用子代理

4. Provider Profile 详解

4.1 是什么

4.2 三个参数

4.3 小例子：动态 header 注入

4.4 重要限制

5. 注册键格式：哪个模型匹配哪个 Profile

5.1 两种键级别

5.2 注册示例

5.3 查找优先级

5.4 不支持通配符

6. 合并语义：重复注册会发生什么

各字段合并规则一览

7. YAML/JSON 配置文件方式

7.1 HarnessProfileConfig --- 可声明的子集

7.2 完整示例：用 YAML 配置

7.3 反向导出：从 HarnessProfile 导出为 Config

8. 插件式分发：让它自动加载

8.1 pyproject.toml 配置

8.2 Python 注册函数

8.3 加载顺序

9. 完整实战示例

9.1 场景：为 Qwen 模型定制 Agent 行为

9.2 场景：模型切换 --- 不同的模型不同的行为

9.3 场景：YAML 驱动的运维配置

10. 常见问题与排查

10.1 Profile 没生效？

10.2 想移除 FilesystemMiddleware 但是报错

10.3 多个 Profile 叠加后行为不符合预期

10.4 插件 Entry Point 没有自动加载

11. 总结

核心概念速查

推荐实践

3.2 核心类：`HarnessProfile`

3.3.1 `base_system_prompt` --- 替换基座提示词

3.3.2 `system_prompt_suffix` --- 追加后缀提示（最常用）

3.3.3 `tool_description_overrides` --- 覆写工具描述

3.3.4 `excluded_tools` --- 移除不需要的工具

3.3.5 `excluded_middleware` --- 移除中间件

3.3.6 `extra_middleware` --- 追加额外中间件

3.3.7 `general_purpose_subagent` --- 配置/禁用通用子代理

7.1 `HarnessProfileConfig` --- 可声明的子集