Appearance
定制、中间件与 Profiles
Deep Agents 提供的是默认 Harness，不是封闭产品。应用可以替换模型、增加业务 tools、调整 system prompt、扩展 state/context schema、加入 middleware 或结构化输出。Profiles 则把与 provider 或模型 相关的 Harness 差异注册成可复用配置。
常用定制入口
| 参数 | 作用 | 不应用来做什么 |
|---|---|---|
model | 模型字符串或 chat model 对象 | 在文档中固定易过时模型名 |
tools | 业务与 MCP tools | 代替真正授权系统 |
system_prompt / systemPrompt | 领域职责与行为约束 | 存放密钥或大量动态数据 |
middleware | hook、state、tool 与模型调用扩展 | 绕过内置安全边界 |
state_schema / stateSchema | 扩展 thread state | 存放跨用户长期数据 |
context_schema / contextSchema | typed runtime context | 直接暴露给模型全部字段 |
response_format / responseFormat | 最终结构化结果 | 约束所有中间 ToolMessage |
checkpointer / store | thread 与跨 thread 持久化 | 自动提供租户授权 |
前端类比
这些入口类似框架的 app config、middleware、request context、store adapter 与 response schema。 Profiles 更接近按运行目标自动选择的一组 bundler preset，而不是用户业务设置。
Deep Agents 原生语义：create_deep_agent/createDeepAgent 先构造核心 middleware stack，再把 自定义配置与 state/context schema 交给 LangChain create_agent。Profiles 根据模型/provider key 调整 Harness 默认值，并不是一个传给每次调用的 profiles= 列表。
扩展 State 与 Runtime Context
Python 可以在稳定核心 API 上定义额外 state channel 和 typed context：
python
import os
from dataclasses import dataclass
from deepagents import create_deep_agent
from deepagents.graph import DeepAgentState
from pydantic import BaseModel, Field
class AppState(DeepAgentState):
project_id: str
@dataclass
class RequestContext:
user_id: str
tenant_id: str
class Report(BaseModel):
summary: str
evidence_paths: list[str] = Field(default_factory=list)
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
state_schema=AppState,
context_schema=RequestContext,
response_format=Report,
)DeepAgentState 已包含内置 reducer 和 Harness 所需字段；自定义 state 必须继承它。一般优先让 middleware 声明自己需要的 state，避免所有页面都共享一个不断膨胀的全局 schema。
Runtime context 由应用在 invoke 时提供。工具可以使用其中的认证身份派生 Store namespace，但 不应让模型提交 tenant_id 覆盖真实身份。
自定义 Middleware
Middleware 适合实现：
- 在模型调用前裁剪或补充非敏感上下文。
- 为工具调用添加审计 metadata、timeout 或速率限制。
- 对模型结果做业务验证或结构化失败反馈。
- 向 state 增加特定 channel 和 reducer。
Deep Agents 会按 middleware name 合并自定义项：与内置名称相同的项可以替换对应位置，新项会 插入核心 stack 与尾部 memory/HITL 之间。依赖精确 hook 顺序时必须查看当前版本源码并写测试。
不要为了改变一段 system prompt 就重写整个 FilesystemMiddleware；优先使用公开参数和最小 自定义 middleware。
Beta Harness Profiles
Beta：Profiles 的配置格式、注册机制和字段仍可能变化。它适合库作者或平台团队处理 provider/model 差异，不应成为业务配置的第一选择。
Harness profile 可以定义：
- base system prompt 或 suffix。
- tool description overrides。
- excluded tools 或 middleware。
- extra middleware。
- general-purpose subagent 调整。
注册后，Deep Agents 在选择相应 provider/model 时自动应用。调用站仍然使用普通 create_deep_agent(model=...) 或 createDeepAgent({ model })，不需要传递一组 profiles。
Python 与 TypeScript Profiles 差异
| 能力 | Python | TypeScript |
|---|---|---|
| Harness profile | HarnessProfile、register_harness_profile | registerHarnessProfile |
| YAML/JSON 配置 | HarnessProfileConfig | parseHarnessProfileConfig |
| Provider profile | 支持，可影响模型构造 kwargs | 当前不支持 |
| 包插件注册 | 支持 importlib metadata entry points | 当前不支持 |
Python provider profile 用于模型构造默认值、凭据检查或 runtime-derived kwargs；Harness profile 在模型构造后调整 Deep Agents Harness。两者不能混为一类。
定制决策顺序
- 先用默认 Harness 和最小业务 tools 验证任务形状。
- 用公开参数调整 prompt、subagents、skills、memory 与 backend。
- 有横切逻辑时增加小型 middleware，并为 hook 行为写测试。
- 只有当多模型差异需要集中维护时才注册 Beta profile。
- 需要固定控制流时下探到 LangGraph，而不是继续堆 prompt 与 middleware。